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VIEWPOINT 


By the Marshall Clo w 


PalmSource 2000 


Report from the Palm Developers’ 
conference 

Introduction 

PalmSource 2000 was held at the Santa Clara Convention 
Center on December 12ih~15th, 20(X). There were over 3500 
developers in attendance, up from about 2000 in 1999, As a 
result of this growth, Palm announced that starting in 2001, 
PalmSource would be held in the (much larger) San Jose 
convention center. 

Carl Yankowsi. CEO of Palm, Inc. gave the opening 
keynote, setting the tone for the week. He described Palm's 
vision of the “Mobile Internet", where people have access to on¬ 
line resources no matter where they are. 

Slides and WehCasts of the many of the conference 
presentations are available at http://www.palmsource.com. 

News 

Palm is currently riding high, with an 83% (US) market 
share in the handheld computer market. This was reflected in 
the list of Palm OS licensees. There are large consumer 
electronic companies like Sony, computer manufacturers such 
as IBM, and Palm-only companies like Handspring and TUG. 
Symbol is making Palm OS-based bar code scanners for use 
in enterprise applications. 

They have created partnerships with several cell phone 
makers: Kyocera, Nokia, Motorola, and Samsung. Palm is 
working with these companies to put Palm OS capabilities into 
the next-generation (also known as 3G) ceil phones. 

Palm announced at the show that they have more than 
130,000 registered developers, up from about 20,000 last year. 

Palm OS 4,0 

Each developer (after singing an NDA) received a 
prerelease version of Palm OS 4.0. There were several sessions 
devoted to features that will be introduced in Palm OS 4.0, and 
how to take advantage of them. Slides of many of these 


presentations are available on the PalmSource website. Some of 
the new features are: 

* Secondary Storage 

Palm OS 4 will support external file systems and secondary 
storage. This will allow users to keep dam on devices such as 
smart cards or CompactFlash. Sony, a Palm OS licensee, was 
showing a Palm OS device with a slot for a MemoryStick. 

* Attention Manager 

As Palm OS devices are used for more and more tasks, more and 
more applications need to get the users attention. Under Mac 
OS, this is done using the Notification Manager, tn Palm QS, 
applications use die Attention Manager. This allows the user to 
respond to single or multiple events, and allows the applications 
to prioritize notifications (simple vs, insistent, for example). 

* Exchange Manager 

In Palm 05 3 and before, the Exchange Manager was tied to 
the 1R port, since that was the only way dial people could 
exchange data. In 4.0, exchange is transport-independent. 
Tlie big driver for this, as far as I can see, is BlueTooth. 
However, this will also allow people using pager cards, SMS, 
etc. use the same mechanism as the built-in lit port. 

* Telephony 

Since Palm is building relationships with several mobile 
phone vendors, you should not be surprised to learn that 
Palm OS 4,0 will contain a full “phone control” API. As well 
as the basic functionality, there will be also support for SMS 
(via the Exchange Manager). 

Palm OS 5-0 

As w ell as 4.0, Palm gave attendees a glimpse of a future OS 
that they were calling Palm OS 5.0. (this is not an official name) 
David Fedor of Palm said that they expected that devices would 
ship with this OS in 2002. A few of the features previewed are: 


Marshall has worked for Palomar Software. HP T Aladdin Systems and Adobe 1 , Among other things, he has written PICT Detective, Aladdin's Resource 
Compression Toolkit, and way too many resource-processing tools. When he's not coding, lie can lie found mountain biking with his kids or checking 
out microbreweries. He can lx j reached ai <marshall@idiu.com> 
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* Support for ARM processors 

* Better multimedia support 

* Support for different screen sizes and resolutions 

* A wide range of devices, both in price and capabilities. 

The big change for 5,0 is the change to the ARM processor. This 
will be quite an undertaking for Palm, since all existing Palm OS 
applications are written for the Motorola 68000 processor. In some 
ways, this will be even mote difficult than Apple’s switch from the 
680x0 to the PowerPC because the ARM is iittle-endianA like the 
80x86, rather than “big-endianA like the 68K and PowerPC, Palm 
will lie supplying a 68K emulator in their new devices, so that 
existing applications can be run on new machines. 


Developer Tools 

Metrowerks announced at the show (and shipped soon 
thereafter) CodeWarrior 7 for Palm 08. It includes an updated C/C++ 
compiler, all the IDE enhancements from CodeWarrior 6 for Mac OS 
and Windows, and several Palm OS-specific tools, including a 
debugger plugin tliat lets you symbolically debug your Palm OS 
applications either inside POSE or on an actual device. CodeWarrior 
for Palm OS runs on lx>th the Mac and Windows. 

Developer's Nation has formed a partnership with Palm to 
maintain and extend the Palm OS knowledge base, which is a 
great resource for Palm OS developers. This online Q&A 
database should be available by the time you read this at 
http;//www,DevNation,net. 

AppForge announced the release of Visual Basic for Palm 
OS, allowing developers who prefer to write their applications 
in Basic to create Palm OS applications* More information is 
available at http://www.appfGrge.com, 

Extended Systems <http://www.extendsys.conn> announced a 
set of developer tools geared towards the enterprise market, for 
integrating Palm OS devices into a medium to large company. 

Last year at PalmSource '99, Palm and Bear River 
announced that they would be developing and releasing the 
“Palm Development Framework”, a C++ class library for 
developing Palm OS applications. This year. Bear River 
announced that they had completed the Framework, which Is 
available at http://www.bearriver.com/developer/palm/. 

Summary 

Last year, at PalmSource '99, 1 thought that this was an 
exciting time to be a Palm OS developer If anything, this year 
promises to be even more exciting. Even though Palm has an 
80% market share, they aren’t sitting on their laurels; they are 
working hard on improving their products. 

Last year, Palm beat the drum about enterprise support. 
Most of the sessions at PalmSource *99 were about getting into 
and supporting the enterprise market. This year while Palm 
talked quite a bit about the enterprise market, there were 
“personal" sessions as well. 

If you couldn’t make It to PalmSource 2000, be sure to 
check out http://www.PalmSource.com where slides for most of the 
sessions are available. 

See you at PalmSource 01 in October! 
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PROGRAMMING 

TECHNIQUES 


By Rich Allen 
Edited by Cal Simone 


Chart generation with AppleScript & Excel 


A friend of mine likes to say 
“everything is easy once you know how”, 
Updating an Excel spreadsheet and 
generating an accompanying chart is easy 
using a little AppleScript, and Microsoft 
Excel, once you know how! 

People like charts. Charts are an easy 
way of seeing a lot of data and 
understanding it with a quick glance. 
Using AppleScript to update an existing 
workbook, a simple Visual Basic macro for 
exporting a chart as a JPEG file and the 
iDo Script Scheduler included with OS 9 is 
all you need Lo create a regularly updated 
chart. This article will explain how to 

* Use AppleScript to parse a data file for 
required values 

■ Transmit those values to Excel 


First let’s look at using AppleScript to open a file of raw data 
and parse out Lhe values that we really want. For our raw data 
file, we will use a tab-delimited text file as shown in Listing 1. 


Listing 1: Sample raw data 

Date Hour PhoneNum Type Members Peg Busy Usage 
12/20/00 095551234 DNH 3 7 0 17 

12/20/00 095552345 DNH 4 9 0 34 

12/20/00 09 5553456 DNH 2. 1 0 3 

12/20/00 09 5554486 DNH 4 5 0 6 


For this project, we require the values under the 
headings labeled "Date”, “Hour”, “Peg” (number of telephone 
calls), and “Usage" (connect time of all calls) for telephone 
number 5554488, We will assume that this raw file is updated 
once each hour, although we wall want to verify this, and that 
our chart will track peg values versa usage value count on an 
hourly basis. The Excel workbook will be pre-built with two 
worksheets; one containing the chart (chart) and another with 
the values that feed that chart (data). See Figures 1 and 2 for 
examples of these worksheets. 


• Tell Excel to export a chart as a JPEG 
file for use as part of a web page 

* Flow to setup iDo so the chart is 
updated regularly 

A note on conventions used in the 
AppleScript source listing; those words 
that have an underline are application 
keywords. These terms have a specific 
meaning to either the enclosing tell block 
or to AppleScript itself. See the preferences 
panel of your script editor for 
implementing this option. 


55544BS 



Figure i. Sample chart output , 


Rich Allen currently works for a local telephone company in Alaska in the traffic-engineering department. He has held 
a variety of telecommunications positions since 1984 and has designed a number of Macintosh based data systems. His 
email address is g3pb<ialaska.net. 
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Figure 2* Property declaration. 


OK, let’s start writing a script! The script will use three 
properties, values that will he used throughout the script. 
These properties designate the path to the folder containing 
our files, the name of the raw data file, and the telephone 
number to find. See Listing 2, 

Listing 2; Sample of worksheet data 

property folderPath : “MacHD: Desktop Folder: Macleeb: " 
property filename : “rawdata M 
property phoneNumber \ “5554488* 

It is always a good idea to have a try block around 
scripting statements to catch any error that may arise. The 
main portion of the script, Listing 3* is completely enclosed 
in a single try block. Any error encountered will be handled 
by the on error section. Ft>r example, if the raw data file can 
not be found when AppleScript tries to open it, an error will 
occur, passing control to the on error routine. 

The script starts by setting fileftef to an empty string. By 
doing this, if an error does occur, the error handler will be able 
to determine if the data file is open, if so, closing it. If the error 
routine is invoked and £Lldfef is die empty string, then the 
error was generated while attempting to open the file thus 
there wilt be no need to execute the close access statement. 

Next the script will attempt to open the raw data file, 
concatenating the folderPath and CileName properties into a 
single string as input for the open for access statement and 
assigning the resulting file reference number to the variable 
EileRef. From this point on, we can access data from the file 
by referring to the fileRef variable. We know that the data 
file is tab-delimited (a tab character seperates each value in 
the file), so next, the script is set to use the tab character as 
its text item delimiter. (Normally AppleScript’s text item 
delimiter is set to an empty character Since we already 
know that each value of interest per line is separated by the 
lab character, by setting AppleScript's text item delimiters 
to a tab we can easily refer to any value by its position*) 

The sample data file contains eight items per line; in this 
case the date, the hour, phone number, phone number type, 
number of members associated with the phone number, a 
peg count, number of busies and the usage. The variable num 
will be set to the empty string and wall later be set to die 
telephone number from each line that is read from the data 
file and then compared to the property phoneNuiriber to 
determine a positive match. 
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Al this point the script is ready to start reading each line 
of the data file until it finds a match of the phone number 
read and the desired number. Reading a line of the data file 
is done with the standard read statement; reading from the 
current file position until the next encountered return 
character. If the two telephone numbers do not match, the 
next line is read and phone numbers compared. If the desired 
phone number is not found before the end of the file (eof) is 
reached then an error will be created by AppleScript and 
handled by the on error portion of the run handler, otherwise 
the close statement will be executed to close the data file. 

listing 3: The run handler 

try 

sex oldDelimiter to A ppleScript 's text item delimiters 
set AppleScript r s text item delimiters to tab 
set fileRef to "" 

set fileRef to open for access (folderPath & fileName) 
set mim to 

repeat until num is phoneNxunber 

set dLine to read fileRef before return 
set num to text item 3 of dLine 
if (phoneNumber is num) then 
UpdateWorkbook[dLine) 
end if 
end repeat 

close access fileRef 

set AppleScript^ tex t. .item , delim i t ers to oldDelimiter 
on error errMsg number errNum 
if fileRef is not Mn then 
close access fileRef 
end if 

set AppleScript 's text item delimiters to oldOelimiter 
end try 


Once a match has been found, the Update Workbook handler 
(Listing 4) is called. (A handler is basically equivalent to a 
subroutine.) The script starts with a tefl statement that will 
direct any statements following towards Excel. For any 
statement within the tell block that are not directly 
understood by Excel, those statements will be handled by 
AppleScript itself (e.g, if). 

The first statement to Excel will open the required 
workbook by combining two of the properties set initially 
and adding the “.xls” suffix to match the exact file name and 
path of the required workbook. Since the workbook contains 
more then one worksheet (chart and data), the script selects 
the data worksheet to assure the values from the raw data file 
will be inserted into the proper cells. 

For this workbook and chart we are tracking 24 hours of 
data. The data worksheet contains a header in the first row 
with the following 24 rows containing Lhe last 24 hours worth 
of data. Refer back to Figure 2 for an example. 

We will want to verify that the raw data we have read is 
new before we update the worksheet. By comparing the 
hour from the line of raw r data with the last hour on the data 
worksheet (cell B25), we can be sure that the raw data has 
been changed. 

Since we want our chart to show peg versa usage 
information on an hourly basis, we will want to drop the 
oldest hour’s data from our chart and add the newest data. 
By copying the last 23 hours data values (rows 3 through 
25) and then pasting those values into the first 23 hours 
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data (tows 2 through 24), the script has effectively dropped 
the oldest hour, (Note that the copyobject keyword, used 
here, comes from Excel's Custom Suite — unfortunately 
Excel does not have the standard copy verb as many other 
applications do.) Rows 24 and 25 are now the same. To 
add the newest data, the script will simply set the new 
values in row 25, overwriting the extraneous values. 

Now that all the values have been updated, it's time to 
export a copy of the chart for use on the well page. Excel 
has an export function using VisualBasic that can 
accomplish this (the macro is contained within the 
workbook). We will not delve into Excel VisualBasic 
macros in this article but will show the macro we re using 
here in listing 5. AppleScript uses the evaluate statement to 
communicate with Excel to run the macro, Be sure to note 
the syntax here, evaluate requires the file name of the 
workbook concatenated w ith the name of the macro w ith 
the exclamation point character separating them. 

The last job for the Update Workbook handler is to save 
the changes made to the workbook and close the 
workbook file. 

Listing 4: The UpdateWorkhook handler 

on UpdateWorkbook(dataLine) 

tell a ppltcatlon “Microsoft Excel* 

open (foIderPatb & phoneNumber & ".xla*) 
select sheet “data" 

if ( text item 2 of dateline * value of cell *$E$25") then 
gelect ran g^ ("$A$3:$D$25"j 
C p p y Obj g q t selection 
select tanse (“$A$2 : 5D$24"J 

paste 

set value of cell “$A$25 i ' to text Item 1 of dataLine 

set value of cell to text item 2 of dataLine 

set value of cell “$C$25 M to text item 6 of dataLine 

set value of cell “$D$25 H to text item 8 of dataLine 

evaluate (phoneNumher & “ , xls 3 ExportChart (.) ") 

close AstiveWorkbpak aa vi m ££& 
end if 
end tell 

end UpdateWorkbook 


Listing 5= VisualBasic macro to export chart as JPG 

Sub ExportChart() 

Charts("Chart"),Export _ 

EileNarae:=*jJbO:Desktop 
Folder :MacTech i 5554488 - jpg'* 

End Sub 

Each time the script Is run it will update the workbook 
and export a new chart for use on a web page. This script 
does not provide a method of performing this task on a 
regular basis so how do we get it to run on a schedule? 
One solution is to use the iDo Script Scheduler that is 
included with the Mac OS. If it is not already in your 
control panels folder, you will find it on the Mac OS 9 CD 
in the CD Extras folder in the AppleScript Extras folder. 


Open the iDo Script Scheduler control pane! and click 
on the New button. Give this event a name, set the trigger 
to “repeating”, and select the start time and date. All that 
is left is to click the Choose button, select the script 
(which we’ve saved as a compiled script), and save the 
newly created event. Your chart will now be updated 
every hour at the specified time. See Figure 3 for an 
example of the iDo event. 



Although this is a short script with only limited error 
checking, it does demonstrate the ease of integrating 
AppleScript with Microsoft Excel to create charts suitable 
for use on any web page! 

My friend also has another thing he likes to say, “Now 
that I know how, it's easy!” 10 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boonstm, Westford, MA 


DragSort 

Hi confess, Fve done it. More than once, actually. It’s probably not 
legal, strictly speaking. But how bad can it be, I mean, lots of people 
must do it. It’s not something trnly evil like, well, like Napster, 

What am I talking about? Downloading music From the internet. 
Music that other people posted, music that 1 haven’t purchased Yet, 
that is. Music posted to the UseNet alt.binaries,sounds * newsgroups. 

What does this have to do with the Programmers Challenge? 
Downloading Usenet binaries is a (perhaps contrived) motivation for 
this month's problem, that of sorting a list oF items in a particular w ay, 
Dirge binaries are posted in a sequence of parts, and newsreaders 
thread the parrs based on sequence information included by 
convention in the subject line. But sometimes the subject line contains 
information that confuses the sequencing, meaning that the parts need 
to lx.' sorted manually before the binary information can be extracted. 
With the newsreader I use, die parts are sorted by dragging items from 
one position in die fist to another position, until the parts appear in the 
correct order. 

Your Challenge is to find an efficient way to perform this sort. 
Efficient in this case means minimizing the amount of tiresome 
clicking and dragging needed to put the parts in the correct order 
Specifically, you want to minimize the cumulative number of 
positions that you need to move to select the part to be dragged, 
and the number of positions you need to drag the parts. An 
example in a later paragraph will make this a little clearer. 

Oh, and before you turn me in to the authorities, downloading 
music from die internet allows one to sample the music before 
deciding whether to buy it. We all, of course, buy what we keep. 

The prototype for the code you should write is: 

typedef struct Hove I /* describes moves used to sort itemsToSort 7 
long selectPosition; r select this item in rhc array,origin 0 7 
lo ■ i g d ragToPo s i t i on; f drag selected item u ) ibis position in the ;imv r < irigin 

07 

I Move; 


Sounds simple and boring, right? The catch Ls in how your sort 
solution is scored. You are penalized one print for each position move 
your solution makes while performing die sort - one point for each 
position between your current location and the aelectPosition of the 
next Move, and one point for each position lx tween that selectPosition 
and the dragToFosition. When a Move is completed, your current 
position is the dragToPbsrtion, The penally for the next Move Ls the 
number of positions between die previous dragToPositton and the 
current selectPosition, plus the distance from the current selectPosition 
and the current dragToPosftiory etc. 

Imagine, for example, that you are asked to sort the follow ing Esq 
with a startPosition of 0: 

6 12 3 5 4 

You might employ a bubble sort. Your Gist Move is to select the 
2nd item in die list and move it to the 1st position, at a exist of two 
penalty points (moving from [0] to I ] I. and dragging from [1| to 101). The 
list now looks like this: 

16 2 3 5 4 

Next you might move the 3rd item to the 2nd position, at a cost 
of 3 penalty points (moving from [01 to \2\ and dragging from [2| to [ID, 
leaving the list like diis: 

1 2 6 3 5 4 

Then you might move the 4th item lo the 3rd position, at a 
cost of 3 more penalty points. Then the 6th item to the 4th 
position (cost 3 points), and die 6th item to Lhe ith position (cost 
3 points). The list would then be correctly sorted, at a cast, if I 
have counted correctly, of 16 points. 

And you would lose the Challenge, 

A more successful contestant would sort the list ai a cost of 7 
points as follows: 


long r mini Moves 7 DragSort( 

long itemsToSort [], f* array of items to be sorted 7 


); 


long numItemsToSort, 
long startPosition. 
Hove sortMoves[] 


r number of itemsToSort 7 
t item initial) selected 7 
t store Moves tliat sort the my here 7 


Your DragSort routine will lx called with a list of itemsToSort, a 
count of the number of items in die list (numltemsToSort}. and the 
element of the list initially selected (selectPosition). DragSort should 
calculate a sequence of Moves that reorder the list into ascending order 
by moving the item located at one position in the list i selectPosition.) to 
another position in die list (dragToPosition). Moves are returned in the 
sortMoves array, and the number of Moves needed to sort the array 
should lx returned by DragSort. 


6 12 3 5 4 

123546 (cost 5 points) 
123456 (cost 2 points) 


In addition to the |X tints incurred for dragging list items around, 
a penalty of 1 point will lx assessed for each millisecond of execution 
lime, Tlie winner will lx die entry dial correctly sorts a sequence of 
lists while accumulating the fewest penalty points. The Challenge prize 
will lx divided between die overall winner and die Ixst scoring entry 
from a contestant that has not won the Challenge recently. 

This w ill ix a native PowerPC Challenge* using the CodeWarrior 
Pro 6 environment. Solutions may lie coded in C, C++, or Pascal. You 
may provide a solution in Java instead, provided you also provide a test 
driver equivalent to the C axle provided on die web for this problem. 
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Points 


Three Mo>ths Ago Winner 

Congratulations to Tom Saxton Ibr winning die December 
Crutches Challenge. Motivated by a broken foot injury' to a member of 
the family t this variation on the traveling salesperson problem required 
contestants to find optima) way of moving a set of objects from one 
location to another, operating with connectivity constraints among the 
locations, and limited by a maximum carrying capacity* The object was 
to minimize a score that was a combination of the length of the path 
traversed and the amount of execution time required to complete the 
solution* Toms entry was not the fastest, but it did compute a more 
optima] path than the second-place entry by Ernst Munter. 

Tom first calculates the distance from each node to each other 
node in the _MapConneations function. He then calculates a baseline 
solution in the _CalCrutchesCore routine, a solution that picks up the 
closest object when nothing is being carried, delivers the closest object 
when something is being carried, and tries to move objects closer to 
their eventual destination when there is spare carrying capacity, Tom 
then successively refines die baseline solution until a time allocation Ls 
exceeded Refinement uses a variant of the “Algorithm of the Gods”, 
published in Scientific American in March, 1997 (see 
http://www* sci e ntifi camerica n * co m/0397i ssue^O397a mscs. html ) * Basically* the 
algorithm makes small perturbations in the baseline solution to see if 
die perturbed solution results in a lower cost. 

Ernst's entry w as approximately three times faster tlian Tom s, but 
it resulted in lass optimal solutions. Actually, Ernsts solutions were 
slightly shorter in approximately half of die test cases, but Tom's w ere 
shorter by 1/3 to 1/2 in die larger test cases, giving him the win. 

1 used 12 test cases for evaluation, where the number of nodes 
ranged from 10 to 200, the number of connections was as high as 2200, 
and the number of tasks to be accomplished ranged bom 20 for the 
small graphs to 300 for the larger graphs. 

The table Mow lists, for each of the solutions submitted, the total 
execution time, the cumulative distance traveled to accomplish all of 
the delivery' tasks, and the number of points earned As points were 
incurred based on distance traveled and elapsed time, a smaller 
number of points w r as better. As usual, the number in parentheses after 
the entrant's name is the total number of Challenge points earned in 
all Challenges prior to this one. The solution marked with an asterisk 
did not complete die larger problems in a reasonable amount of time. 


Name 

Total 

Distance 

Total 

Code 

Dam 

Lang 


Time ( msec) 

Moved 

FMints 

Size 

Size 


Tom Saxton f l6S > 

12773.5 

456815 

512018 

8004 

586 

C++ 

Erast Munter (701) 

4408,6 

557477 

2Xnll 

4852 

324 

C++ 

J.s. 

ft 

ft 

ft 


344 

C++ 


Top Contestants ... 

Listed here are die Top Contestants for the Programmers 
Challenge* including everyone who has accumulated 20 or more 
points during the past two years. The numbers below include points 
aw arded over the 24 most recent contests, including points earned by 
this month’s entrants. 


Rank Name Points Rank Name 


l 

Munter, Ernst 

281 

5. 

Boring, Randy 

52 

2, 

Saxton, Tom 

96 

6. 

Shearer, Rob 

48 

3. 

Maurer, Sebastian 

68 

7. 

Taylor, Jonathan 

36 

4. 

Rieken, Willeke 

65 

8. 

Wihlbotg, Claes 

29 


and the Top Contestants Looking for a Recent Win 

in order to give some recognition to other participants in the 
Challenge, we also list the liigli scores for contestants who have 
accumulated points without taking first place in a Challenge during the 
past two years. listed here are all of those contestants who have 
accumulated 6 or more points during the past two years. 


Rank 

Name 

Points 

Rank 

Name Points 

9. 

Downs. Andrew 

12 

17. 

Stout, Joe 

10 

10. 

Jones, Dennis 

12 

18. 

Hakt Ladislav 

7 

11. 

Day, Mark 

10 

19. 

Miller, Mike 

7 

12* 

Duga, Brady 

10 

20. 

Nicolle, Ludovic 

7 

13. 

Fazekas, Miklos 

10 

21. 

Schotsman, Jan 

7 

14. 

Flowers, Sue 

10 

22. 

Widyatama, Yudlii 

- 

15. 

Sadetsky, Gregory 

10 

23. 

Heithcock, JG 

6 

16. 

Selengut, Jared 

10 





There are three ways to earn points. (1) .scoring in the top 5 of 
any Challenge, (2) being the first person to find a bug in a published 
winning solution or, ($) Ming the first person to suggest a Challenge 
that 1 use. The points you can win are: 


1st place 

20 points 

2nd place 

10 points 

3rd plate 

7 points 

4th place 

4 points 

3th place 

2 points 

finding hug 

2 points 

suggesting Cliallenge 

2 points 


Here is Tom’s winning Crutches solution; 


Crutchcs.cpp 
Copyright © 2000 

Tom Saxton 

it 

U Cnitches Challenge Solution, December 2000. 
it (c) 2000,Tom Saxton 

it 

//include "Crutches.h* 

/findtide <Events.h> 

ffinclude <stdio,h> 

//include <stdlib*h> 

//include Cnalh.h) 

// the basics 

eninn [ fFalse = 0 * fTrue 3 1 ) ; 

// disable asserts 
//define Assert (t) 

// how long should wc spend trying to find a better answer? 

//define dtickSecond 60 
//define dtickMax [1‘dtickSecond) 
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// random 

static unsigned short URand(unsigned short uMac); 

// heapsort 

typedef unsigned long INDEX: 

typedef Int (*FFNCMP)(INDEX il, INDEX i2. void 'pv) ; 
extern void HeapSort(void ‘prgfoo, INDEX iMac, int cbFoo, 
PFNCMP pfncmp); 

// maximum distance value 
^define distMax 0x7FFFFFFF 

// struct Hits for mapping problem to node indices 

typedef struct TSK TSK: 
struct TSK 
I 

long itaskObject; 
long inodeStart; 
long InodeCur; 
long InodeDst; 
long wgt: 
int fWanted; 
long rankDrop; 

TSK 'ptskNext; 

): 


typedef struct ENODE ENDGE: 
struct ENODE 
t 

long inode; 

Node node; 
long cobj; 
long rankGrab: 

1; 

// connection map stuff 
typedef struct CONN CONN; 
struct CONN 
1 


DATA RECOVERY: 
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// base information for this connection 
long inodel; 
long inodeZ: 
long diet: 


typedef struct CMAP CHAP; 
struct CMAP 

l 

long dlstDirect; 
long distPath; 

h 

typedef struct NODC NODC; 

struct NODC // node connection,used when looking for paths between nodes 

I 

long distFromStart: 
int fCheckNeighbors; 
h 

static CONN 'sj>aconn; 
static long s_cconn: 
static CMAP *s_pacmap; 
static NODC *s_panodc; 

// million global* 
static const Node *s_pariQde; 
static ENODE *s,pdnnode: 
static long s_cnode; 
static TSK *s_patBk; 
static TSK ‘s^ptskFirst; 
static long s_ctsk; 
static long s_vgtCa.rryMost: 

// core algorithm stuff 

static long _GactCrutchesCore(long inodeStart* Action paact [] , 
long caetMax, long distStop, long 'painodePath, 
long “paitskOrder. long ‘paitskOrderUsed, long *pdist); 
static long _InodeGetTarget(long InodeCur* long cobjCarry. 

int fUseWantedFlag. long ‘paitskOrder. long 
*pcnodeOrderGrab * 

long 'pctskOrderDrop]; 

static void ^ Rand oral zeGrderUong iTry* long cTry, long etsk, 
long cnode, const Long paitskOrderQId[1 , 
long paitskOrderNcw[]); 

// translation helpers 

static long, _lnodeFroinNode (Node node); 

static int „CmpEnodeNode(INDEX il, INDEX 12, void *pv); 

static int _CmpEnodeInode(TNDEX il* INDEX 12, void *pv): 

// action functions 

static int _FTakeStep{long inodeDst, long cactMax* 

Action paactf], long 'pcact, long ‘pinodeCur, long *pdist) ; 
static int J?FollowPath(long cattMax, Action paactf], 
long 'pcact, long *pinodeCur, long *pwgtCarry, 
long *pcobjCarry, long cnodePath, const long painodePath[]); 
static int ^FGrabObject(long cactMax, Action paact[], 

long *pcact, long *pwgtGarry, long ‘pcobjCarry, long inode, 
long Itsk): 

static int _FDropGbject(long cactMax. Action paact [], 

long 'pcact, long 'pwgtCarry, long ‘pcobjCarry, long inode, 
long itsk): 

// connection map functions 
static void _MapConnections(long cconn, 
const Connection paconnection[]): 
static void _FreeConnectionMap(void); 
static int _FConnectedNodes (long inodel, long inode2, 
long *pdist); 

static long _CnodeFindMinFath(iong inodeStart, 
long inodeEnd, long painodePath[]); 
static void _ComputeNodeDistanc-es(long inode): 
static long _InodeNearestTask(long InodeCur); 
static inline long _MstNodeToNode(long inodel* long inodeZ) 

f 

return s_pacmapfinode2's_cnode + inodel],distPath; 


static void _ResetState{); 

static TSK '_PtskRer)oveTsk (TSK *ptsk); 
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long /* actions in solution 7 Crutches ( 
const Node pauode[], 
long cnode, 

const Connection pacouncetion[] # 
long cconn, 
const Task patask[]* 
long ctask« t objects to be moved, numbered as index into objectsToMove 7 
Node node Start, /* srait from this node 7 

Weight wgtCarryMost t t maximum weight that you can carry 7 

Action paact [], t return youf solution here 7 

long cactMax /* size of soluhonpaih army 7 


t Nodes defining die problem 7 
r number of Nodes 7 
■ t Qmnectitms between nodes 7 
t mimlier of Connections 7 
r objects to be moved 7 


long cactBest “ 0: 
long ‘paitskOrderTry = NULL: 
long ‘paitskGrdecBest = NULL: 
long ‘paitskOrdertlsed = NULL: 
long ‘painodePathBuffer = NULL 


// start die dock running.. 

long tickStart = TickCountO; 


// allocate the memory buffers we need CMapG>nnections also allocates memory) 

try 

I 

s_pdnnode = new ENODE[cnode]; 

a_patsk = new TSK[s_ctsk = ctask]: 

paitskOrderTry = new long[ctask+cnode]; 

paitskOrderBest = new long[ctask+cnode]; 

paitskQrderUsed = new long[ctask+cnode] ; 

painodeFathBuffer 3 new long[s_cnode]; 

I catch (...) t 

printf("Bob, can I have some more memory? 

I need %ld bytes, plus some more for the 
connections map.YfT, 
sizeof(ENGDE)*cnode 
+sizeof(TEK)*ctask 
+sizeof(long)*(ctask+cnode)*3 
+sizeof(long)*s_enode 
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if (s_pdnnode = NULL | ] s„patsk = NULL | | 

paitskGrderUsed “ NULL | | paitskOrderTry = NULL | 
paitskOrderBest = NULL 11 painodePathBuffer = NULL) 
goto LCleanup; 

// initialize the node entry array 

s_cnode = cnode: 
s_panode = panode; 

for (long inode = 0: inode < cnode; -H-inode) 

t 

ENODE * penode = &s_pdnnode[inode] ; 
penode->inode = inode: 
penode->node = panode [inode]; 
penode->cobj = 0: 

} 

// sort node entries by node value 

HeapSort(s_pdnnode, cnode. sizeof fs_pdnnode[0])„ 
_CiripEnodeNode] * 

// fill mTSK reeoitls, with inode values 

for (long itask - 0: itask < ctask: ++itask) 

l 

TSK *ptsk = &s_patsk[itask]: 
const Task ‘ptask “ Apatask[itask]; 

ptsk-KtaskObject “ itask: 

ptsk->inodeStart = _InodeFromNode(ptask->fromNode]: 
ptsk ■ >inodeDst = _lnodeFrcmiNode(ptask->toNodeh 
ptsk->wgt = ptask'kweight: 

I 

_MapConnections(cconn. pacomiection); 
long inodeStart = _InodeEromNode(nodeStart); 

U sort node entries by node index 

HeapSort{s_pdnnode, cnode♦ sizeof(s_pdnnode[0 ]), 

_CrapEnodeInode): 

// get the baseline solution 

JtesetStateO : 

s_wgtGarryMost = wgtCarryMost; 
long distBest: 

cactBest _CactCrutchesCore(inodeStart, paact. caciMax, 

distKax, painodePathBuffer* NULL, paitskGrderUsed, 
AdistBest); 

// if we have ;i nontrivial number of tasks, try- to improve our elution using partial 
// ordering info from tile baseline 

// based loosely on “Algorithm of the Godst Sdentilie American* Mandi 1997 

if (ctask > 2) 

I 

long distToAccept = distMax: 
long clter = 0: 

long clterMax = 10 * cconn 11 ctask; 
long dtickNext = 0: 

B1ockMove(paitskOrderUsed, paitskOrderBest * 

sizeof (paitskOrderBest [0]) * (ctask+cnode)) i 

for (long dtick = TickCountO; 

(dtick tickStart) < dtickMax && clter < clterMax: 
++clter, dtick m TickCountO) 
l 

_Reset£tate{) ; 

_RandomizeOrder(dtick, dtickMax, ctask, cnode, 
paitskOrderBest, paitskOrderTry}; 

long distTry; 

long cact = _CactCrutchesCore(inodeStart* paact+cactBest, 
cactMax-cactBest, distToAccept, painodePathBuffer, 
paitskOrderTry, NULL. AdistTry): 
if (distTry < distToAccept) 
i 

distToAccept = distTry: 

BiockMove £ paitskOrderTry, paltskOrderBest, 
sizeof(paitskOrderBest[0])*(ctask+cnode)): 

if (distTry < distBest) 

{ 

distBest = distTry: 

BlockMove(paact+cactBest * paact, cact * sizeof(paact[0])); 
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cactBest - cact; 


I 

I 

) 

1 

LCleanup: 

JFteeConnectionKapO: 
if (s_patsk ]= NULL) 

{ 

delete s_patsk; 
a_patsk = NULL: 

I 

if [s_pdnnode 1= NULL) 

[ 

delete s_pdnnode; 
s_pdnnode = NULL: 

) 

if (paitskOrderTry != NULL) 
delete paitekOrderTty: 
if (paitekOrderBest != NULL) 
delete paitskGrderBest; 
if (paitskOrderUsed 1“ NULL) 
delete paftskOrrferUsed; 
if CpainodePathBuffer 1= NULL) 
delete painodePathBuffer: 

return cactBeat; 


.CactCnjrdiesCore 

// core function to computer a solution, possibly using a partial node /1 a sk 
ordering array 

static long _CactCrutcheaCore( 
long inodeStart, 

Action paact[], 
long cactMax, 
long distStop, 
long *painodePath* 
long ‘paitakOrder. 
long 'paitakOrderUsed, 
long *pdist 


int fSuccess = fFalse; 
long inodeCur = inodeStart; 
long cnodePath - D: 
long iinodePath = 0; 
long cact = 0: 
long wgtCarry = D; 
long eobjCarry = 0: 
long inodePath - -1; 
long inodeTarget “ -1; 

long cnodeOrderGrab - 0. ctskOrderDrop = 0: 


f 

long iitskRank, iinodeRank; 

// reset the priority ranks 

for (iitskRank " 0; IitskRank < E_ctak; -H-iitskRank) 
e_patsk[iitskRank].rankDrop = -1; 
for (iinodeRank = 0; iinodeRank < E_cnode; ++iinodeRank) 
E_pdnnode [iinodeRankl, rankGr ab = -1; 

// if wc have a priority order set task ranks 

if [paitskOrder != NULL) 

1 

for (iitskRank = 0; iitskRank < s_ctsk; ++iitskRank) 
s_patsk[paitskQrder [iitskRank]].rankDrop = iitskRank; 

for (iinodeRank = 0; iinodeRank < s_cnode: ++iinodeRank) 
5_pdnnod e[p ait s kOrde r[s_ct s k+iinodeRank]].rankG rab = 


for (long itskCur = ‘pdist = 0; itskCur < s_ctsk; ) 


TSK ’ptskT; 

long inodeNext = -1; 

// drop any objects whose distillation is the current node 

if (cobjCarry > 0) 

I 

for (ptskT = s_ptskFirst: ptskT 1= NULL; ) 

I 

if (ptskT-HnodeCur = -1 &Sr ptskT -HnodeDst = inodeCur) 

{ 

If ■( !_FDrop0bject (cactMax, paact H fitcact. &wgtCarry, 
&cob]Carry, inodeCur, ptskT - s_patsk)) 
goto LCleanup; 
inodeTarget = ■1; 
ptskT = _PtskRemoveTsk(ptskT): 

-H-itskCur; 
continue; 

I 

ptskT = ptskT->ptskNext; 


if (itskCur = s_ctsk) 
break; 

J 


// see if we want to grab or drop items at lliis node 

if (a_pdnnode[inodeCur],cobj > 0) 

t 

_ComputeNodeUistances(inodeCur); 

// dear the wanted flags for all objects 
for (ptskT - s_ptskFirst; ptskT l— NULL; 
ptskT * ptskT'>ptskNext) 
ptskT->fNanted “ fFalse; 

long vgtVanted = 0; 
long cobj Carry Wanted = 0; 
for(:;) 

[ 

H find the object with the nearest desinarion 

TSK ‘ptskWant = NULL: 
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long distBest = distMax; 
for (ptskT = s_ptskFirst; ptskT 1= NULL; 
ptskT = ptskT->ptskNext) 

if (ptskT->fWanted || 

(ptskT-MnodeCur ! = inodeCur && ptskT->inodeCur != -1) 
|| wgtWanted + ptskT->wgt > sjwgtCarryMost) 
continue; 

long distLook: 
if (paitskOrder ]= NULL) 

distLook = ptskT->rankDrap: 
else 

distLook = _DistNodeToNode(inodeCur, ptskT->inodeDst); 
if (distLook < distEest) 

I 

distEest = distLook; 
ptskWant = ptskT; 

) 


// hail if we didn't find anything more to pick up 
if (ptskWant = NULL) 
break: 

// mark the new item as wanted 

ptskWant ->fWanted = fTrue; 
wgtWanted ptskWant->wgt; 
cobjCarryWanted += 1; 


// did anything change? 

for [ptskT = s_ptskFirst: ptskT != NULL: 
ptskT = ptskT->pfskNext) 

if ((ptskT >inodeCur — 1) 1- (ptskT->fWanted !- fFalse)) 

break: 

if [ptskT S= NULL) 

( 

inodeTarget = _lnodeGetTarget(inodeCur. cobjCarryWanted, 
fTrue/^flfseWimtedl 7 lagV, paitskOrder. kcnodeQrderGrab. 
kctskOrderDrop); 
if [inodeFath !- inodeTarget) 


StoneTable 

You thought it was just a replacement 
for the List Manager ? 

We lied, it is much more ! 

Tired of always adding just one more feature to your LDEF or 
table code ? What do you need in your table ? 

Pictures and Icons and Checkboxes ? 
adjustable columns or rows ? 

Titles for columns or rows ? 

In-line editing of cell text ? 

More than 32K of data ? 

Color and styles ? 

Sorting ? 

More ?? 

How much longer does the list need to be to make it worth 
$200 of your time ? 

See just how long the list is for StoneTable. 

Make StoneTable part of your toolbox today ! 

Only $200.00 MasterCard & Visa accepted. 


// make suit wc have a path to die current target 
inodeFath = inodeTarget; 

if ((cnodePath = _CnodsFindMinPath(inodeCur, inodeFath, 
painodePath)) = 0) 
goto LGiveUp: 
iinodePath ~ 0; 

inodeNext - painodePath[iinodePath]; 

// dear items that aren’t going to foe helped foy the path to the new target 

for (ptskT = s_ptskFirst; ptskT J= NULL; 
ptskT = ptskT->ptskNext) 

( 

if (JptskT->fWanted] 
continue; 

_ComputeNodeDistanc es(ptskT->inodeDst); 
if (_DistNodeToNode(ptskT-XnodeDst, inodeNext) > 
_DistfbdeToNode (ptskT->inodeDst. inodeCur)) 

[ 

ptskT->fWanted = fFalse; 
wgtWanted -= ptskT->wgt: 
cobjCarryWanted = 1; 

) 


// drop items we re carrying dial we no longer want 

for (ptskT - s_ptskFirst: ptskT !- NULL; 
ptskT ■ ptskT-kptskNext) 

if £ ptskT-HnodeCur = -1 && [ptskT->f Wanted) 
if (1 JFDr'opflbJisct(cacttta. paact, &cact, kwgtCarry, 
kcobjCarry. inodeCur. ptskT s_patsk)) 
goto LCleanup: 

// grab warned items wt'it nut earning 

for (ptskT =■ s_ptskFlrst; ptskT I* NULL; 
ptskT = ptskT->ptskNextj 

if (ptskT-)inodeCur — InodeCur ptskT->fWanted) 
if (t_PGrabObject(cactMax. paact. freaef, fcvgtCarry, 
kcobjCarry. inodeCur. ptskT - s_patsk)) 
goto LCleanup; 

1 

// pick the ament target node 
if (inodeTarget — -1) 

inodeTarget - _1nodeGetTarget(inodeCur, cobjCarry, 
f Fa 1 s eril iNeWantedFLigV, pair a kD rder. & c nod eOrd e rGr ab. 
SictskOrderDrop); 

// make sure we have a path to the current target 

if (inodeFath I- inodeTarget) 

t 

inodeFath ~ inodeTarget; 

if [(enodePaih = .CnodeFindMinPalh(InodeCur H inodeFath, 
painodePath)) — 0) 
goto LGiveUp; 
iinodePath = 0; 
j 

inodeNext - painodePath[iinodePath]: 
if (-H-iinodePath )= cnodePath) 
inodeTarget = inodeFath = -1; 

// drop any objects not helped by our pending move 
if (cobjCarry > 0) 
f 

for [ptskT = s_ptskFirst; ptskT 1= NULL: 

ptskT = ptskT->ptskNext) 

i 

if (ptskT -HnodeCur != -1) 
continue: 

_ComputeNodeDistances(ptskT->inode0stj; 
if (_DistNodeToNode(ptskT-HnodeDst, inodeNext) > 
_DistNodeToNode(ptskT->inodeDst. inodeCur)) 
if (LFDropGbject(cactMax, paact, &caet, &wgtCarry, 
&cobjCarry, inodeCur, ptskT - s_patsk)) 
goto LCleanup: 


// move 


StoneTabiet Publishing 
More Info & demo Voice/FAX (503) 287-3424 

http://www.teleport.com/~stack stack@teleport.com 
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www.faircom. com/maca 


573.4aS.6S33 


+39-035-773.464 


FairCom Offices 

USA_ 

EUROPE 
JAPAN 


+8159-3 39.7504 


What shape is your database project? A tiny embedded database that requires a small 
footprint but demands rigorous functionality? Or a huge multi-platform, multi-user, multi- 
headache project? Have you struggled to find a better solution for your data access 
requirements, only to feel like you’re sacrificing one requirement over another? 

FairCom has delivered uncompromising database technology to commercial developers for 
over twenty years, with the primary goal of keeping control in the hands of the developer. Our 
customers rely on the speed, flexibility, scalability and reliability of c-tree Plus. The high 
performance and low cost of ownership make c-tree Plus an excellent choice for all sizes of 
database development projects. 


Proven Database Technology 

Besides the ISAM-level control and speed, perhaps the most important reason why small 
development houses and Fortune 1000 companies have chosen FairCom technology is the superior 
service offered by our sales and support staff. Our development staff understands the challenges 
you face, and we’ll put our twenty years of experience to work to help you build better solutions. 


Single Solution for Diverse Implementation 


Vertical Markets 
Embedded Systems 
Web & ASP Markets 


E-Commerce 
Smart-Cards 
Web-Enabled Appliances 


NO DBA 


Comprehensive Feature Set 

• Royalty-free single user and multi-user 
support with full source code 

• Client/server and custom server support 

• Robust server side SDK - build your own application 
specific database server with full source available! 

• Thread compliant + portable thread API 

• Full featured transaction processing with savepoints, 
abort and full rollback 

• Comprehensive security and encryption features 

• Small footprint 

• Fixed and variable length records and keys 

• Store any data type - up to 18 million terabytes! 

• Dynamic space reclamation 

• ODBC and Crystal Reports™ drivers 

• Full ISAM functionality 

• Powerful stand-alone index support 


Multiple-Platform 

Support 

Mac OS, Mac OSX, MkLinux, 
Linux {PPC, Intel, SPARC, Alpha), 
Windows 95/98/ME/2000/NT, 
Novell Netware, Solaris (SPARC, 
Intel), Sun OS, OS/2, AIX, HP UX, 
SCO UnixWare, Interactive, AT&T 
Sys V, QNX, 880PEN, FreeBSD, 
Lynx, Banyan Vines, and more... 


Supports ADSP, 
SPX, TCP/IP 


Looking for more speed, scalability 
and reliability from your database? 
C-tree Plus is the perfect fit! 


BRAZIL +55,1L3872,9802 Cotwamon ether company 

— --f—-——— ----- ' — ■ —’—and! product names are registered tradamarka 

or trademarks of their resfiewrve owners. 


Mac Support; Since 1985 • USA. 800.S34.8180 • info@faircom.com 




































if {LFTakeStep(inodeNext. ta.ct.Max, paact, &cact. kinodeCur, 
pdist)) 

goto LCleamip: 

if (*pdist > distStop) 

l 

// fix the object counts 

for (long inodeClean = G: inodeClean < s„cnode; 
'HinodeClean) 

s_pdnnode[inodoCleart] .cobj = 0; 
goto LGiveUp: 

J 

1 

// set the actual ordering used 
1 ong it skOrder, inodeOrder; 
if (paitskGrderUsed E= NULL) 
f 

for (itskOrder “ 0; itskOrder < s_ctsk; ++itskOrder) 

( 

TSK *ptskSetOrder = &s_patsk[itskOrder]: 

if (ptskSetOrder-> rankBrop = -1) 

ptfikSetiSrder->rankDrop = ctskOrderDrop-Lf; 
paitskOrderUsed[ptskSetOrder->raukDrop] = itskOrder: 

1 

for (inodeOrder = 0; inodeOrder < s_cnode; 'H’inodeOrder) 

[ 

ENQDE 'penode = &s_pdnnode[inodeOrder]: 
if (penode->rankGrab = -1) 

penode->rankGrab = cnodeOrderGrab’H-; 
paitskOrderUsed[s_crski-penod£-> rankGrab] = inodeOrder: 

I 

I 

LGiveUp: 

fSuccess = fTrue; 

LCleamip: 

if (ifSuccess) 

*pdist ” distMax; 
return each: 


sor 



Professional Software Developers 

Looking for career opportunities? 
Check out our website! 
Nationwide Service 
:nt Assistance 
le Help 
Assessment 
Never a fee 

Scientific Placement, Inc. 
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JncxteCetTarget 

static long _InodeGetTarget(long inodeCur* long cobjCarry H 
int fUseWantedFlag. long *paitskOrder* 
long ‘‘pctiodeOrderGrab. long *pctsk0rderDrop) 

t 

TSK 'ptsk: 

// if we haw a chosen order, use that 

if (paitskOrder 1= NULL) 

I 

if (cobjCarry = 0) 

I 

long inodeGrab = -1; 
long rankGrab = e_cnode; 

for (long inode = 0: inode < s_cnode: -Hinode) 

I 

EN0DE *penode = &s_pdnnode[inode]; 
if (penode->cobj = 0) 
continue: 

if (penode->rankGrab K rankGrab) 

I 

rankGrab = penode->rankGrab; 
inodeGrab = inode; 

I 

1 

return inodeGrah: 

I 

else 

[ 

TSK 'ptskChoose = NULL: 
long rankChoose = s_ctsk: 

for(ptsk = s_ptskFirst: ptsk 1 = NULL: ptsk = ptsk->ptskNext) 

int fCarried = fUseWantedFlag ? ptsk->fWanted : 

ptsk->inodeCur = -1; 


// only consider carried objects 

if (SfCarried) 
continue: 

// pick the one with the lowest rank 

if (ptsk-)rankDrop < rankChoose) 
t 

rankChoose = ptsk-^rankDrop; 
ptskChoose = ptsk; 

I 

I 

remm ptskChoose- >inodeDst: 


// otherwise if we're not carry ing anything, go to the nearest node with an object 

CoraputeNodeDistances(inodeCur); 
if (cobjCarry = 0) 

f 

// pick the Dearest node with a task 

long inodeTarget - _InodeNearestTask(inodeCur): 

// try to assign a priority to this node 

if (s_pdnnode[inodeTarget].rankGrab = -1) 

s_pdnnode[in Dd eTarget], rankGrab - (■*pcnbdeOrderGrab) ++; 
return inodeTarget; 

1 

// otherwise deliver die object with the nearest destination 

TSK *ptskDeliver = NULL; 
long distBest = distMax: 

for (ptsk - s_ptskFirst; ptsk 1- NULL; ptsk = ptsk->ptskNext) 

[ 

if (fUseWantedFlag ? 1 ptskOfWaated : ptsk->inodeCirr I" 1) 
continue: 

long distLook - _DistNodeToNode(inodeCur, ptsk->inodeDst); 
if (distLook < distBest) 

1 

distBest - distLook: 
ptskDeliver = ptsk: 

] 

J 

if (ptskDeiiver-^rankDrop — -1) 

ptskDeliver->rankDrop = [*pctskOrderDrop)++: 
re turn pt s kDellve r ~ >inod eDs t: 
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ffpragma mark - 
// annealing functions 


_Randomi^eOrder 

static void _RandomizeOrder(long iTry, long dry, long ctsk. 
long (inode, const long paitskOrderOld []. 
long paitskOrderNew[]) 

1 

// copy the old to the new 

BIockMove(paitskOrderOld. paitskOrderNew. 

sizeof(p&itskQrderNew[0]]* *(ctsk+cnode)): 

// swap some [xnrs of elements 

long cpairSwap = 1 + (ctsk + cnode) * (cTry-iTry)/(4-cTry); 
while (cpaicSwap- >= 0} 

( 

long itski, itsk2; 

// swap tasks or nocks? 
if (URandfctsk + cnode] K ctsk) 

t 

// swap tasks 

itskl = URand(ctsk); 

Itsk2 = URand{ctsk-l): 

I 

else 

f 

// swap nodes 

itskl = ctsk + URand(cnode); 
itsk2 = ctsk + URand(cnode-1); 

) 

if (itsk2 >- itskl) 

4H-itsk2; 

long itskT = paitskGtdierNew [itskl ]: 
paitskOrderNew[itskl] =* paitakOrderNew[itsk2]; 
paitsk0rderNew[itsk2] = itskT: 

) 

) 

// utilities for translation to inode problem 
^pragma mark - 


InixidTomNodc 

// Uriel the index to ilte specified Node 

static long _InodeFromNode(Node node] 
f 

long iinodeMin t iinodeLast: 

iinodeMin = 0; 
iinodeLast = s_cnode ■ 1; 

while (iinodeMin < iinodeLast) 

I 

long iinodeMid “ {iinodeMiu + iinodeLast + 1)/2: 

if (sjpdnnode[iinodeMid]*node > node) 
iinodeLast = iinodeMid 1: 
else 

iinodeMin = iinodeMid: 

I 

rettim s_pdnnod a [ iinod eMi n 1 * i node: 

1 


JimpEnodeNode 

// compare two ENODE entries by their node values for HeapSort 

static int _CmpEnodeNode{INDEX il, INDEX 12. void *pv) 

f 

ENODE "pdnnode = (ENODE ‘)pv: 

return pdnnode[il],node ■ pdnnode[12]- node; 

I 

// compare two ENODE entries by tlxrir inode values for HeapSort 

static int _CmpEnodelnode(INDEX il* INDEX 12. void *pv) 

( 

ENODE *pdnnode = (ENODE *)pv; 

return pdnnode[il].inode - pdtinode [i2].inode: 

] 

^pragma mark - 


JTakeStcp 

static int _FTakeStep(long inodeDst. long cactMax. 

Action paact[]. long *pcact, long *pinodeCur, long 

*pdist) 


if £*pcact >= cactMax) 

[ 

printf("QGM in _FTakeStepYn" J: 
return fFalse; 

1 

long dist: 

if (|_FC.onnecTedNodes (‘pinodeCur * inodeDst, &dist)) 
return fFalse: 

*pdist += dist: 

*pinodeCur = inodeDst: 

Action ‘'pact = &paact[(*pcact}-H-] : 
pact->action = kMoveTo: 
pact->node = s_panode[inodeDst]; 
return fTrue; 


_FGmbObject 

static int _FGrabObj ect{1ong cactMax. Action paact[]* 
long *pcact„ long ‘pwgtCarry, long *pcobjCarry, 
long inode t long itsk] 

I 

if (*pcact )- cactMax) 

[ 

print f ("OOM in _FGrabObject\n' h ) : 
return fFalse: 


Action *pact = Spaaet[(*pcact)++]; 
TSK *ptsk “ &s_patsk[itskl: 

pact->action = kPickUpQbject; 
pact->objact = ptsk-HtaskObject: 

ptsk’>inodeCur = -1; 
sjpdnnode(inode],cob] 1: 

++(*pcobjCarry)j 
*pwgtCarry += ptsk->wgt; 


Felt Tip 

Sound Studio 

Record and Edit Audio 

with a sound editor designed for the Mac. 

Sound Studio will alfow you to make quick edits with an 
interface as easy as a text editor. Add polish to recordings 
with fades, normalization, and edits. Create your own mixes. 
Transform them with effects. 

Sound Studio features 

* up hi 13 bits, 2 channels, and 65 kHz 

■ up to 2 GB of audio 

* AIFF, Sound Designer 2 r WAVE. 

System 7 Sound, and QuickTime import 

■ edit with sample accuracy 

* fade, amplify normalize, and invert 

* delay, echo, reverse, and swap channels 

* smooth and emphasize 

* resample and pitch shift 

* snap to zero crossings, snap to grid 

$35 

Sound Studio 

download free 14-day trial 
or order online at 

www.felttip.com 

Qi^dmms is iradewark, uied undpr begnse_ puce in US drtldi* 


Felt Tip Software, 807 Keely Place, Philadelphia PA 19128-2326, USA 
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return fTrue; 

I 


_EDropObfcct 

static int _FDropGbject(long cactMax. Action paact[]* 

long *pcact, long ‘pwgtCarry. long 'pcobjCarry, 
long inode. long irsk) 


if (*pcact >= cactHax) 

{ 

ptintf ("00M in _FDropObjeccVn”); 
return fFalse; 

J 

Action *pact = kpaact [(*pcact)++]; 
TSK *ptsk = &s_patsk[itsk] : 

pact->action = kDropQffObject; 
pact->object = ptsk>itaskObject; 

ptek>inodeCur = inode; 
if [ptsk->inodeBst != inode) 
s_pdnnode[inode].cob j t= 1: 

—{*pcobjCarry); 

*pwgtCarry -= ptsk->wgt; 

return fTrue: 


^pragma mark - 


JAapConnwtkHis 

static void jHapConnections(long cconn* const Connection 
paconnection[]) 
l 

E_Gconn 11 cconn; 
try 


s_paconn = new CONN [cconn]; 

Assert(s_pacmap = NULL); 

s_paemp = new CMAP[s_cnode*s„cnode]: 

for (long iT = s_cnode 4 s_cnode; -IT >= O'; ) 

f 

s^pacmap [IT].distDirect = - i; 
s_pacmap [iT]*dietPath - -1* 

I 

s_panodc = new NODC[s_cnode] : 

I 

catchC*.,) 

I 

printf( w Bob. I need more memory, somewhere 

around tld bytes\rT, 

sizeof(CONN)*cconn 
+sizeof(CHAP)* s_cnode' s_enode 
+sizeof(WODC)*s_cnode 
): 


for (long iconn = 0: iconn < cconn; t+iconn) 

f 

CONN *pconn = &s_paconn [iconn] ; 

const Connection ‘pconnection = tpaconnection[iconn] ; 

pconn >dist — pconnection’Mistance; 

pconn-Hnodel = _TnodeFromNode(pconnection hnodel): 

pcorm->inode2 « _lnQdeFromNode(pconnection->nDde2); 

s_pacmap [pconn->inodel*s_cnode + pconn 

>inode2].distDirect - 

pconn->dist; 

s_pacmap[pconn->inode2‘s_cnode + pconn- 

>inodel].distDirect = 

pconn->dist: 

I 

I 


BasePlant 

200 classes to enhance PowerPfant™ 


• AppleEvents 

• AppleScript 

• Collection Manager 

• Data Browser 

• Disk Item Filter 

• Folder Parser 

• Icon Services 

• Multiprocessing 

• Preferences Manager 

• Starting Point 
•Window Proxy 

And Much More! 

SI 49 For commercial in-house development 
$35 For personal freeware and shareware 
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_FreeConnectionMap 

static void _F ree Connect ionMapO 

if (s_,paconn != NULL) 

( 

delete s_paconn: 
s_pacarm = HULL: 

] 

if (s_pacmep != NULL) 

! 

delete s„pacmap: 
s_pacmap - NOLL: 

I 

if {s_panodc t= NULL) 

delete s_panodc; 
s,..panodc = NULL: 

I 

) 


_F(Jonnt*clcdNodcs 

static int _FConnectedNodes[long inode!, long lnode2* 
long *pdist) 

long distT: 
if (pdist = NULL) 
pdist = &distT; 

•pdist = s_pacmaplinodel*s_cnode + inode2].distDirect: 
return *pdist != -1; 


_G>mpuTeNodd)tetanccs 

static void _ComputeNodeDistances(long inode) 

f 

if (s_pacmp[inode*s_cnode + inode] .distPatb = -1} 
_GnodeFindMinPath(inode -071:0, inode. NULL): 

1 


_CnodeFindMinPath 

static long _CnodeFIndM inPath(long inodeStart. long inodeEnd, 
long painodePath[]) 

[ 

if (inodeStart = inodeEnd) 
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A New System is Coming 



netOctopus is ready. Are you? 


Mac 05 X ts coming. (t*s right around the corner, You may 
be going through your preparation checklist right now, 
wondering if you have enough time: 

Inventory all installed software 
i/ Check software versions 

✓ Check hard disks and memory on all computers 

✓ Identify hardware upgrade needs 
1 / Print summary reports 


With netOctopus, you can do all of that with a few mouse 
dicks. Then, when OS X arrives, get the new version of 
netOctopus, and use it to distribute all of your new software 
throughout your network seamlessly. 

Timbuktu Pro, the # i remote control and file 
transfer software for the Mac, integrates seam¬ 
lessly into netOctopus, for even greater net- 
Ti FTlbuktu work support! 



With netOctopus, you would practically be ready for 05 X today. 
Without netOctopus, you may be running out of time. 



www.netoctopus.com 
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fExpanded = fTrue; 


return 0: 

// dear the NODC array 

for (long inode = 0; inode < s_cnode; ++inode) 

I 

e_panodc [inode] .dietFrotnStart = distMax; 
s_panodc[inode].fCheckNeighbors = fFalse; 

] 


// seed the fill with the end node 

S_panodc[inodeEnd].distFromStart = 0: 
s_panodc[inodeEnd],fCheckNeighbors = fTrue: 

long distPathKnown = s_paemap[inodeStart*s_cnode + 
inodeEnd] .diEtPath; 


// expand exit from base node until we've exhaused all possibilities 

for (int fExpanded = fTrue: fExpanded; ) 

l 

fExpanded = fEalse: 

for (long inodeSrc = 0: inodeSrc < s_cnode; ++inodeSrc) 

f 

if £!s_panodc[inodeSrc]*fCheckNeighbors) 
continue: 

for (long inodeDst = 0; InodeDst < s_cnode; -HinodeDst) 

t 

long dint: 

if (inodeSrc = inodeDst | 

LFConnectedNodes(inodeSrc, inodeDst, &dist)) 
continue: 

if (s_panodc[inodeSrc].distFromStart + diet < 
E_panodc [inodeDst]►distFromStart] 

! 

s_panodc[InodeDst]«distFrutnStart “ 

s^anodc [inodeSrc] .distFromStart + diet: 
s_panodc[inodeDst].fCheckNeighbors = ‘fTrue: 


if [inodeDst = InodeStart kb distPathKnown != 1) 

if (s_panodc[inodeDst].distFromStart == 

distPathKnown) 


goto LHaveFath: 



II operates lOO's and sometimes a 1000 
times faster than other systems 


Valentina (AppleScript)(68K/PPC/X) $49 

Valentina C++ SDK (68K/PPC/X/Win32) $499/fi99 

Valentina for Java (PPC/X/Win32) $299 

Valentina for REALbasic (PPC/X/Win32) $199/299 

Valentina for Director (PPC/Win32) $199/299 

Valentina XCMD (PPC/Win32) $199/299 

Valentina for WebSiphon (PPC) $299 


Make your application's database operations hlazingly fast! 

order Directly www.paradigmasoft.com 

from Our Web Site Hosted by MacServe.net 


Download full featured evalution version 


J 

) 

s_panodc [inod e S r c ]. f Chec kNe i ghb o r s = f Fal se; 

} 

1 

// if we need to. record the results for this node 

if (s_pacmap[inodeEnd*s_cnode i inodeEnd].dietPath “ -1) 

i 

for (long inodeConnect = 0: inodeConnect < s„cnode; 
^inodeConnect) 

! 

long diet = s_panodc [inodeConnect).distFromStart: 
s„pacmap [inodeConnect *s_cnode + inodeEnd].distPath = 

dist: 


s_pacmap[inodeEnd g s_cnQde + inodeEnd].distFath = 0: 

I 

// walk from the start node to the end node 

LHavePath: 

if £s_panodc[inodeStart] .dietFromStart — distHax) 

1 

printf["Hey! There's no way to get from node %ld to node 
%ld1\n", s_panode[inodeStart], s_panode[inodeEnd]); 
return 0; 

1 

long cnodeFath; 
long inodeCur; 

for (cnodePath * 0* inodeCur = inodeStart; 

inodeCur != inodeEnd; ++cnodePath) 

I 

long inodeNext: 
long disconnect; 

long distCur = s„panodc[inodeCur1.distFromStart; 
for (inodeNext = 0; inodeNext < s_cnode; ++inodeNext} 
if LFConnectedNodes(inodeNext * inodeCur♦ 

&distConnect) kb 

s_panodc[inodeNext].distFromStart + disconnect “ 
s_panodc[inodeCur] .distFromStart), 

break: 

if (painodePath != NULL) 

painodePath[cnodePath] = inodeNext; 
inodeCur = inodeNext: 


return cnodeFath; 


JnodeNearestTask 

static long _InodeNearestTask(long inodeCur] 

t 

// find the nearest object 
long distBest ~ distMax; 
long inodeBest = -1; 

for (long inodeLook = 0; inodeLook < s_cnode; ++inodeLook) 

{ 

if (sj>dnnode[inodeLook].cobj = 0) 
continue; 

long dist = _DistNodeToNode(inodeCur, inodeLook]; 
if Tdist C distBest) 

( 

inodeBest = inodeLook: 
distBest = dist: 


return inodeBest; 


^pragma mark - 


_RcsctStatc 

static void _ResetState() 


// fill in object counts in dnnode 
for (long itsk = 0: itsk < s_ctsk; ++itsk) 
[ 

TSK *ptsk ” &s_patsk[itsk]: 
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ptsk-> inode Cue ” ptsk->inodeStart: 
if [ptsk-MnodeCur 1= ptsk-MnodeDst) 
s_pdnnode [ptsk- HnodeCur] < cobj += I \ 

// chain the records together 
ptsk->ptskNext = ptsk+i; 

) 

// set up the pointers at the start and end of die list 
s_ptskFirst *■ s_patsk; 
s_patEk[s_ctsk-lI .ptskMext & NULL: 


_PtskReiooveTs 

static TSK *_PtakRemoveTsk(TSK 'ptsk) 

{ 

TSK **pptsk - ks_ptskKirst: 
while ((‘pptsk) 1= ptsk) 

pptsk = &(*pptsk)->ptskNexx; 

TSK ‘ptskNext “ ptsk->ptskNext: 
ptsk>ptskNext = NULL; 

*pptsk = ptskNext: 
return ptskNext; 


^pragma mark ■ 


HRand 

// return a random number in die range |0, uMaxj 
If NOTE: this only works for values that fit into a short 

static unsigned short URand[unsigned short uMac) 

I 

unsigned short u, uLim: 

ff remove bias toward small numbers 
^define wRandMax OxFFFF 

Assert (sizeof(int) > sizeof(short)): 

Assert(uMax < wRandMax); 

Assert (wRandMax > 0 ( wRandMax+1) > wRandMax) : 

uLim = wRandMax - ((wRandtlax+1) % uMac); 
do 
I 

u - (unsigned short)Random () : 

I while (u > uLim): 

return u \ uMac; 

] 

// heap sort code 

static void _Swap( INDEX il* INDEX 12, void *pv, int cbFoo); 


HeapSort 

void HeapSort(void ‘prgfoo, INDEX iMac* int cbFoo. PFNCHP 
pfncirip) 

f 

INDEX iTop, iLast, iUnder, iCur; 

if UMac -= 0) 
return; 

iTop - iMac/2: f* first initial lint* worker V 

iLast — iliac 1: f* die lost clement */ 

for (:;} 

{ 

if (iTop > 0) 

1 

r hire a new supervisor, put him in his place 7 

-iTop; 

I 

else 

I 

r retire the chairman of the board, 
r trickle the List line worker into his correct spot 

n 

_Swap(lLast. 0. prgfoo, cbFoo): 

if (iLast- <— 1) 
return; 

I 


ICur = iTop; /* new supervisor 7 

IUnder = iCur + iCur + 1; f* first underling 7 

while (Hinder <= iLast) 

f 

t compare to the Lxiier underling 7 

if (iUnder < iLast) 

if (Upfnanp)(iUnder, iUnder+1, prgfoo) < 0) 

-H-iUnder: 

if ((‘pfnetop) (iCur, iUnder, prgfoo) < 0) 

{ 

f promote the underling 7 

Jjwap(iCur, Hinder, prgfoo, cbFoo}; 

t check the demoted "supervisor 1 against Ills new- underlings 7 

iCur = iUnder; 

iUnder += iUnder 1 1; /* first underling of demoted supervisor 7 

else 

I 

r we re done silting, terminate loop 7 

break; 

I 

) 

J 

I 


_Swap 

static void _Swap (INDEX il, INDEX 12, void *pv, int cbFoo) 

I 

char *pbl, *pb2. bT; 
int cb; 

pbl = (char*)pv + (long)iI*cbFoo: 
pb2 = (charUpv +■ Uong)i2*cbFoo: 

for [eb = cbFoo; cb-; ) 

t 

bT - *pbl: 

*pbl++ - *pb2; 

*pb2+l = bT; 

1 

] 

m 
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PowerTools for Programmers 


CodeWarrior for Mac OS is, a powerful integrated 
development environment that includes a folly object 
oriented application development framework called 
Power PI ant. With CodeWarrior for Mac OS you can quickly 
develop reliable, professional quality applications that 
execute on Classic Mac OS, or OS X. 


REALbasic is the programming tool for The rest of us," Each 
window type, control, and menu is preconfigured and instantly 
works as it should. The drag and drop Window Editor allows 
you to quickly and easily create your application's Interface so 
you can focus on the important part--your creativity, includes 
900 page manual, examples and tutorial on CD ROM! The 
professional version has all the power of the standard, plus 
database support and allows you to cross compile your code 
for Windows with a single click! 

As low as 


Spotlight is the first Macintosh "Automatic Debugger" it can 
automatically locate run time errors in your code and display 
the offending source code line. Unlike similar tools on other 
platforms Spotlight is easy to use. No source code changes 
are necessary for application debugging, Spotlight can 
automatically check for wild pointers, memory leaks, 
overwrites, underwrites, invalid dereferencing of handies, and 
even toolbox parameter validity checking spotlight knows 
Macintosh verifying parameters to over 400 toolbox calls. 


VOODOO Server is a version control system for software 
developers using Metrowerks CodeWarrior under Mac OS 
VOODOO Server and the corresponding VOODOO clients (the 
included CodeWarrior VCS plug in and the VOODOO Admin 
application} are designed to offer reliable and robust version 
control features while minimizing the administrative overhead 
that usually accompanies version control. If you're a single 
programmer or managing a team of developers, version control 
can make or break your project. Do it right, with VOODOO 


Resorcerer is the only supported general-purpose resource editor 
for Macintosh. Relied upon by thousands of Mac developers. 
Resorcerer features a wealth of powerful yet easy-to-use tools for 
easier, faster, and safer editing of Macintosh data files and 
resources Whether you have to parse a picture, debug a data fork, 
design and tryout Balloon Help, create a scripting dictionary, create 
anti-aliased icons, design and edit a custom resource with 40,000 
fields in it create C source code to run a dialog, or any of hundreds 
of other resource-related tasks, Resorcerehs magic will quickly save 
you time and money. 


One of the most flexible and powerful development 
environments on the Macintosh today! Easily create programs 
with the visual program editor, drop into the BASIC editor to 
define powerful logic with the worlds easiest programming 
language, or work directly with the Macintosh toolbox. The 
only BASIC compiler on the market that gives you 100% access 
to ail of the power of the Macintosh toolbox! 
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Monitor the bandwidth usage of up to five different machines on your 
network! Do you need to upgrade your Webserver? How hard is your 
eMail server working? Are you getting all the bandwidth you're 
paying For? Not only can CyberGauge answer all these questions, 
new features allow CyberGauge to eMail or page your network 
device becomes unresponsive r passes a threshold of usage you 
define - an essential first line of defense for early detection of denial 
of service attacks and necessity for warning you and tracking quality 
of ISPs that may have brown outs and shutdowns. 


WebSTAR Server Suite is a complete set of powerful and easy- 
to-use Internet servers for the Mac OS. Effortlessly serve web 
pages, host emaif accounts, publish databases, and share files - 
all with a single application on one Mac! WebSTAR Server Suite 
Is perfect for Internet or Intranet serving, single or multiple 
sites, small! and large businesses it s power and ease-of-use 
saves any organization time and money. 


Funnel Web is the ultimate web analysis solution for 
professionals. Specifically designed lor profiling web site usage 
and monitoring customer usaee patterns, Funnel Web is ideal for 
examining server performance and online effectiveness. Funnel 
Web can analyze log file formats from any server, VtebSTAR, 
WebTen. even Unix or NT hosted ervers. Discover the most 
popular pages on your site, track server loads & optimize server 
performance, profile visitors based on organization, domain 
name, country, browser, etc. Funnel Web does it ail! 


NetBarrier offers a Personal Firewall, Antivandal protection, and 
Internet Filtering. Protect your machine from intrusions by Internet 
or AppleTalk. Incorrect passwords and individual actions are 
logged, you are alerted to hostile actions, and intruders are easily 
isolated. Internet Filtering allows you to be sum that passwords, 
credit card numbers, and other sensitive information can never be 
exported from your computer - the content, itself is filtered before 
any transfer! (Rated 4 mice by Macworld Magazine) 
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...and great hardware solutions! 



2 USB PCI Card 


Add two USB ports to your older Macintosh. Connect up to 
127 devices to the Universal Serial Bus [USB) that is 
Apple's new standard for desktop connectivity. USB mouse 
devices, keyboards, joysticks, game controllers, printers, 
scanners — connect, them all to your current computer. 
Installs in minutes) 


Macsense USB Full Size Keyboard 


Just plug this keyboard into your Mac and start typing! The 
UKS-600 keyboard from Macsense is designed to get you 
typing quickly and easily, without any hasste or compatibility 
worries. It features two tone translucent design, colored to 
match your favorite flavor of Macintosh, It offers soft touch 
with positive tactile feedback and build built in USB port on 
either side of the keyboard. Includes a 5' USB cable and is 
100% Macintosh compatible, simply plug and play, as easy 
as Macintosh) 



Dr. Bott Moni Switch ADBm-usB 


Do you need 4 monitors and 4 keyboards for your 4 servers? 
With Dr. BotL Moni Switch you can conned, a single keyboard 
and monitor to up to 4 machines at once! A simple flick of a 
switch directs the video input and keyboard commands to the 
appropriate CPU! Available in USB and ADB models, with 2 
or 4 machine support, and bundles with USB PCI cards so 
you can mix and match USB and ADB machines with the 
same Moni-Switoh! Great for programmers to do back 
ground compiles, ideal for server rooms overcrowded with 
monitors and keyboards! 



Macsense Internet Sharing Router 


Looking to get your whole office online without shelling out 
thousands of dollars? If so, the XRouter Internet Sharing 
Hub offers the perfect solution. This amazing Ethemet-to- 
Ethernet hub connects an entire network of up to 252 users 
to the Internet using only one ISP account and one Cable or 
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QUICKTIME 

TOOLKIT 


By Tim Monroe 


A Goofy Movie 


Working with Sprites in QuickTime Movies 


Introduction 

The major new technology introduced in QuickTime 
version 2.1 (released in 1995) was support for sprites and sprite 
animation, A sprite is a graphical object that has a number of 
properties, including its current image, location, size, layer, 
graphics mode, and visibility state. These properties determine 
the appearance of the sprite at any instant in time. By varying 
one or more of these properties over time, we can animate the 
sprite. For instance, Figure 1 shows the first frame of a 
QuickTime movie that contains one sprite, whose image is the 
original icon for the QuickTime system extension. 


□ =^ 

——’ - — 

icon.mov 1 

g 

^ ' 
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Figure 1: A movie with a sprite 


We can move the icon to die right by gradually changing die 
horizontal location of die sprite. In addition, we can change the 
image associated with the sprite at any time. In this case, we ll 
change the icon from the old QuickTime extension icon to the 
new QuickTime extension icon when the sprite gets to the 
halfway point, as shown in Figure 2. The new icon then 
continues moving at the same rate until it reaches the right side 
of the movie Ixjx. 



Figure 3 shows another sprite movie. In this case, there is 
only one image associated with the sprite for the entire duration 
of the movie, and the sprite location remains constant. Well 
animate this sprite by changing the graphics mode, from totally 
transparent to totally opaque. What wove done here is recreate, 
using sprite animation, the appearing-penguin movie diat was 
the very first QuickTime movie we built in this series of articles 
(see "Making Movies” in MacTech, June 2000}. 



Figure j: The penguin movie using sprite animation 


Tim Monroe Is amazed at how fast his new lizard Libia is growing. Maybe he’ll try feeding insects to his own children to sec if they grow any faster. 
In the meantime, you can contact him at monroe@apple.com. 
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Recall how we went about creating the first version of our 
penguin movie: we opened a picture resource and drew that 
picture into an offscreen graphics world; we compressed the 
data in that graphics world and added it as a frame to the movie 
file. Then we repeated the drawing and compressing 99 times, 
each time with gradually more opacity, to create 99 additional 
movie frames, The resulting movie file contained 100 
compressed images, for a total size of about 472 kilobytes. 

Using sprite animation, we can reduce that size 
dramatically. Our new penguin movie file contains only a 
single compressed image and 100 sets of “instructions" that 
indicate the desired level of opacity in each movie frame, 
The 100 movie frames are generated at playback time by the 
sprite media handler from that image and those 100 sets of 
instructions. The size of the sprite version of the penguin 
movie is only about 36 kilobytes, (No, that's no typo; the 
exact same visual output can be achieved with a file less than 
one tenth the size of our original movie file.) 

Already you can see that sprite animation differs 
significantly from what’s often called cel animation , where 
each frame of the animation is a fully-rendered picture of 
some characters superimposed on a background image, if cel 
animation is like a recorded symphony, then sprite animation 
is more like a set of sounds together with instructions for 
playing back those sounds in the right order and at the right 
time. If the instructions in a sprite movie aren’t too 


complicated, they can be executed at runtime just as 
smoothly as decompressing and playing back the fully- 
rendered version of the movie. Arid, as we've seen, the 
images and instructions can take up a lot less space, 

QuickTime 3 0 extended the capabilities of the sprite media 
handler by adding support for wired sprites, or sprites that react 
to mouse events (and other kinds of events) and that have 
various actions attached (or “wired”) to them. For instance, we 
can use a wired sprite to control the properties of the sprites in 
the movie (so that clicking on one sprite causes another sprite to 
disappear or to change location), Or, we can control various 
aspects of movie playback, such as the volume and balance of a 
sound track, or the graphics mode of a video track. By using 
wired sprites in a movie, we can add a level of interactivity 
previously unavailable in QuickTime. 

In this article, weTe going to learn how to create movies 
that contain sprite tracks. Well see how to create both the 
icon movie shown in Figure 1 and the penguin movie shown 
in Figure 3. Our sample application this month is called 
QTSprites, and its Test menu is shown in Figure 4. 


Tes 


Make Icon Mouie... 361 

Make Penguin Mouie... 362 
Make Space Mouie... *3 

Use Background Image 

Figure 4: The Test menu of QTSprites 
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(The "space movie* is a more complex movie that does sprite 
animation using location changes, layer changes, and image 
changes. We won't learn how to build it in this article, but the 
code for doing so is contained in the file QTSprites.c.) 

Well begin by looking in more detail at sprites and their 
properties. Then we’ll take a look at the structure of sprite 
tracks and see how to build the icon and penguin sprite 
movies. Toward the end, we’ll see how to add some simple 
interactivity to our sprite movies without using wired sprites. 
Well postpone our investigation of wired sprites to an 
upcoming QuickTime Toolkit article. 

Sprite Properties 

In a QuickTime movie, a sprite is a graphical object that 
belongs to a sprite track (of type SpriteMediaType), In the 
simplest case, the basic appearance of a sprite is set by selecting 
one out of an array of images associated with the sprite. The 
current sprite image index is one of the five main sprite 
properties, defined using these constants: 


enum 1 

kSpritePropertyMatrix - 1* 

kSpriteFropertyVisible = 4, 

kSpritePropertyLayer “ 5. 

kSpritePropertyGraphicsMode = 6. 

kSpritePropertylmagelndex = 100 

i: 


The sprite matrix is a 3-by-3 matrix that controls the 
location, size, and rotation of the sprite image within the sprite 
track. (A sprite's matrix is added to the track matrix of the 
sprite track.) The sprite visibility state is an integer value that 
controls whether the sprite is currently visible. (This value is 
interpreted as a Boolean value but is stored in the movie file 
as a 16-bii short integer.) The sprite layer is an integer value 
that determines, when two or more sprites have locations that 
overlap, which sprite is drawn on top of the other sprite(s). 
Sprites with lower layer values are drawn on top of sprites 
with higher layer values; if we want to ensure that some sprite 
is drawn behind all other overlapping sprites, we can set its 
layer to the special value kBackgroundSpriteLayerNum 
(appropriately defined in the file Movies.h as 32767). Finally, 
the sprite graphics mode determines how the sprite is drawn 
into the sprite track. We specify a sprite graphics mode using 
a structure of type ModifierTrackGraphicsMode Record, defined 
like this: 

struct ModifierTrackGrapMcsModeRecord [ 

long gtaphicsWode; 

RGBColer opColot: 

h 

This structure contains the QuickDraw graphics mode and the 
color used by some of those graphics modes. For instance, if 
graphicsMode is blend, then opColor specifies the weight color 
(which determines the amount of blending of the source and 
destination pixels). 

A sprite's current image does nor have to come from a sprite 
image array. Instead, the sprite media handler can use a video 
track in die same QuickTime movie as the source for the sprite s 
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image. This allows us to create even more intricate animations 
than are possible by simply varying the five basic sprite 
properties. As a very simple example, we could create a sprite 
track containing two sprites, one whose image looks like a 
television set and a superimposed sprite whose images are 
derived from a video track. The net effect would be a sprite track 
containing a television playing the video. 

Sprite Tracks 

A sprite track consists of one or more sprite media samples. 
There are two basic kinds of sprite media samples: (1) those diat 
define the sprite image array and set the initial properties of a 
frame, and (2) those that animate the sprites in the track by 
specifying changes to the sprites' properties. The sprite media 
handler relies on the distinction between key frames and 
difference frames, which we encountered in the previous article 
(“Honey, 1 Shrunk the Kids" in MacTech t February 2001), The 
image arrays and initial properties are stored in key frames, and 
the sprite property changes arc stored in difference frames. The 
only departure here is purely terminological: when we’re 
working with sprite data, the difference frames are called 
override frames (because the data in those frames overrides the 
data in the key frames). 

The Format of Key Frame Samples 

The data in both key frames and override frames is stored 
in atom containers. (Indeed, atom containers were introduced in 
QuickTime version 2.1 primarily for the purpose of organizing 
sprite media data.) A key frame atom container contains a child 
atom of type kSpriteAtomType for each sprite in the key frame. 
This atom contains leaf atoms that define the initial properties of 
the sprite. The atom IDs of the sprite atoms are numbered 
sequentially, starting at 1; these atom IDs are also called sprite 
IDs . Figure 5 shows the basic structure of a key frame sample. 



Figure 5: The structure of a keyframe sample 


A sprite atom contains child atoms that define the initial 
properties of the sprite, it can contain a child for each of the five 
basic: sprite properties, as well as an atom (of type 
kSpriteNameAtomlype) that defines the sprite’s name. Figure 6 
shows the structure of a sprite atom. 



Figure 6: The structure of a sprite atom 


As Figure 5 indicates, a key frame atom container also 
contains a single child atom of type kSpriteSharedDataAtomType 
(with atom ID 1) which contains the image data for all the sprites. 
This atom contains one sprite images container atom :, of type 
kSpritelmagesContainerAtomType (also with atom ID 1), This atom, 
in turn, contains one atom of type kSpriteimageAtomType for each 
individual image in the key frame. Note that all the images for all 
the sprites are contained in the single images container atom. 
Figure 7 shows the structure of a sprite shared data atom. 



Figure 7; The structure of the shared sprite data 


k Sp r itc Inti gcIXi Aton/Type 
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The Format of Override Samples 

The structure of an override sample Ls somewhat simpler 
than that of a key frame sample, largely because an override 
sample does not contain any image data. An override sample is 
an atom container that contains a sprite atom (of type 
kSp rite Atom Type) for each sprite that is being animated by that 
override .sample. The sprite atoms contain child atoms for each 
of tile properties that are changing from the previous key frame 
or override sample. Figure 8 shows the structure of a typical 
override sample. 



Figure 8: The struct it re of mi override sample 

The ID of a sprite atom in the override sample should be 
the same as the ID of ihe sprite atom in the key frame atom 
whose data that the override atom is overriding. 

Creating Sprite Tracks 

As weVe just learned, a sprite track consists of key frame 
samples that contain the images for the sprites in a track and the 
initial properties of those sprites, and override samples that 
change one or more of the properties of those sprites. In both 
cases, the sample data is contained in an atom container. 
Building a sprite track is therefore largely a matter of creating the 
appropriate atom containers and inserting them at the desired 
times in the sprite track media. 

Creating Sprite Tracks and Media 

When the user selects an item in the Test menu, 
QTSprites calls the GTApp_HandieMenu function, which is 
shown in Listing 1, 

Listing l: Handling items in the Test menu 

OTAppHandlcMenu 

Boolean QTApp_HandleMemi (UIntl6 theMemiltem) 

I 

Boolean mylsHandled * false; 

switch (theMenuItem) f 

ease IDM_MAKE_IC0NS_M0VIE: 
case 1D«_MAKE_PENGUIN_M0VIE: 
case IDM,MAKE_SPAGE„M0VIE i 

QTSprites_Create5pritesMovie(theMenuItem); 

my Is Hand led = true; 

break; 


case IDM_USE_BACKGROUND_IMAGE; 

gUseBackgroundFictute = tgBseEackgroundPicture; 

mylsHandled = true: 

break; 

// switch (theMenu Item) 
return(myIsHandled); 


As you can see, we call the function 
GTSprites_CreateSpritesMovie to create each of the three sample 
movies, passing in the menu item so that we know w'hich movie 
to create, GTSprites_CreateSpritesMovie is defined in Listing 2, 


Listing 2: Creating a sprite movie 

QTSpriie>_CreateSpritcsMuvie 

GSErr QTSprites_Create£pritesMovie (dint16 theMemiltem) 


Movie tnyMovie = HULL; 

Track myTrack * HULL; 

Media rayMedia » HULL; 

FSSpec myFile; 

Boolean mylsSelected = false: 

Boolean rayIsReplacing “ false; 

Fixed myHeight = 0; 

Fixed myWidth = 0: 

StringPtr myPrompt = 

QTU tils_Con v ertCToPa s c a1£ t r ing (k£ p rit e S ave F r ampt) : 
StringFtr myFileName & 

QTU ti1Con vert CToPa sc a1S t ring{kSp riteSa v eM o vieFi1eName); 
long myFlags “ createMovieFilaDeieteCtirFile | 

c rest eM□vieFileD o nt Ctea t e Res File; 
short myResRefNum = 0: 

short myRe3IT ® movielnDataForkResID; 

OSEtr myErr “ noErr; 


// prompt the user for the destination file name 
QTFrarae_FntFile(myProrapt, rayFIleMame. iinyFile, 

6raylsSelected. imylsfieplacing); 
myErr = mylsSelected ? noErr : userCanceledErr: 
if (imylsSelected) 
goto bail; 


// create a movie file for the destination movie 

myErr - CreateMovleFile(imyFile, FOUB_CHAR_CODE(*TVOD h ). 

sra£ysteiti£crlpt. myFlags, &myResRefNLim, &myMovie); 
if (myErr !- noErr) 
goto bail: 


// create the sprite track and media 

QTSprites_GetMovieSiae(theMenuItem, intyHeight, ^myWidth); 

myTrack = NewMovieTrack(myMovie, myWidth, myHeight, 

kNoVolume); 

rayMedla ~ NewTrackMedia(myTraek. SpriteMediaType, 

kSpriteMediaTimeScale, NULL. 0); 


BeginMediaEdits(myMedia); 

// add the appropriate samples to the sprite media 

switch (theMenuItem) [ 

case 1DM_MAKE_IG0NS_M0VIE: 

QTSprit es_AddIcouMo v 1 e 3 amplesToMe dla(myMedia): 
break; 

case IDM_MAKE_PENGUINJTOVIE: 

QTS p rit es_Add F e n guinMovle £ ample sToMedia(rnyKedia): 
b reak; 

case IDM_MAKE_SPACE_MQVIE: 

QT£pritGs_AddSpaceMovie£amplesToMedia{i!iyMsdia) ; 
break: 
default: 
goto bail; 
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EndMediaEdits(myMedia); 

If add the molia to the track 

InsertMedialntoTrack(myTrack, 0, 0, 

GetMediaDuration(nryMedia), fixed!] ; 

// set the sprite track properties 

QTSprites_SetTrackProperties[myMedia, theMemiltem); 

// add the movie resource to the movie file 

myErr = AddMovieResource(myMovie, jnyResRefNum. fhnyResID, 
myFile .name): 

bail: 

if (myResRefNuin \= 0) 

CIo s eKovieFile(myRe s RefNum); 

if (myMovie ! = NULL) 

DisposeMovie(myMovie); 

free(myPrompt); 
free(myFilename ): 

return(myErr}; 

) 

The GTSprites_CreateSpritesMovie function is remarkably 
similar to each of the other movie-creation functions we’ve used 
earlier in this series of articles (compare, for instance, the 
QTMM_CreateVideoMovie function in “Making Movies" in 
MacTecb, June 2000). There are only three main additions For 
QTSprites. First, since we want to be able to create any one of 
three different sprite movies, we call the function 
QTSprites_GetMovieSize to get the desired size for each of those 
movies, QTSprstes_GetMovieSize is defined in Listing 3- 


Listing 3: Getting die size of a sprite movie 

QTSprites J'i et M uvicSi w 

void QTSprites_GetMovieSize (UIntl6 theMenuItetn, 

Fixed *theKeigbt. Fixed HheWidth) 

I 

if ((theHeighf = NULL) || (theWidth = NULL)) 
return; 

switch (theMenultem) [ 

case IDM_MAKE„ICON£„MOVIE; 

*theWidth = (long)klconSpriteTraekWidth << 16; 

*theHeight = (long)klconSprlteTrackHeight << 16; 

case IDM_MAKE_PENGUIN_MOVTE: 

'theWidth = (long)kPetiguinSpriteTrackWidth << 16; 
HheHeight = Qong)kPenguinSpriteTrackHeight « 16; 
break; 

case IDM_MAKE_SFACE_MQVi£: 

‘theWidth = (long)kSpaceSpriteTrackWidth « 16; 
*theHeight = (long)kSpaceSpriteTrackReight « 16; 
break; 

) 

I 


Tills is pretty simple stuff; we just convert some long integer 
constants to the Fixed data type and return them to the caller. 

Tile second difference between QTSprites_CreateSpritesMovie 
and our earlier movie-creation functions Is that vve use the menu 
item number passed in to select tile appropriate function for adding 
samples to the sprite media. And t third, once we’ve added those 
samples to die media, we call die QTSprites SetTraekProperties 
function to set some sprite track properties. Well consider sprite 
track properties in more detail 
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Setting Sprite Properties 

A key frame sample is an atom container that contains an 
atom of type k Sprite Atom Type for each sprite in the frame (which 
contains the initial properties of the sprite) and an atom of type 
kSpriteSharedDataAtornType (which contains atoms that hold the 
sprite images). So the first tiling we need to do is create an atom 
container, like this: 

myErr = QTNewAtomContainer(&mySample) ; 

Let's begin by adding the sprite atoms to die key frame 
sample, A sprite atom is itself an atom container, because it 
contains child atoms for each of the initial sprite properties we 
want to assign it. (Any properties we don’t explicitly define in a 
key frame sample are set to default values. ) So we need to create 
another atom container, like so: 

myErr = QTNewAtomContainer [&mySpriteData): 

Now we want to add one or more property atoms to the 
sprite atom. For the icon movie, we want to set tire initial 
location, visibility state, layer, and image index. We can set the 
image index, for instance, like this: 

short myIndex = lj 

myIndex = EndianSlfi_NtoB(myIndex); 

myErr = QTInsertChild(mySpriteData, kParentAtoralsContainer, 
kSpritaPropectylroagelnd-ex* 1 . 0 . sizeof (short). 

&myIndex* NULL); 


This code inserts a child of type kSprite Property I mage Index into 
the sprite atom, making sure that the atom data (in this case, a 
slum integer whose value is I) is in big-endian format 

Similarly, we can set die initial visibility state of the icon 
sprite using these lines of code: 

short invisible - true; 
invisible = EndIanSl6_NtoE{isVisible); 

myErr = QTInsertChiId{my£priteData, kParentAtomlsContainer, 
kSprltePropertyVisible. 1. 0. sizeof(short) t 
fid bV isible, NULL): 

(You might have thought that the default value for the visibility 
state of a sprite would be true, but sadly that's not so. So we 
need to explicitly configure our sprites to be visible or they 
won’t be drawn.) 

To increase the readability of our code, well define a utility 
function called SpriteUtiIs_SetSpriteData that allows us to set the 
main sprite properties in one fell swoop. Then we can define die 
initial state of die icon sprite Like this: 

myLocfltian.h = 32: 
myLocatian.v = 32: 
invisible = true; 
myLayer = -1; 
myIndex - 1; 

SpriteUtils_£etSpriteData(mySpriteData, kmyLocation, 

kisVisible, kmyLayer, &myIndex, NULL, NULL, NULL); 

The SpriteUtilsJSetSpriteData function is defined in the file 
SpriteUtilities.C; its definition is shown in Listing 4. 
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Listing 4i Setting p roperties of a sprite _ 

SpriteUtils^SctSpriteData 

OSErr SpriteUtilsjSetSpriteData ( 

QTAtomContainer theSprite. 

Point *theLocation, 
short *theVisible. 
short *theLayet, 
short *theIraagoIndex, 

ModifierTrackGraphicsModeRecord *theGraphicaMode t 
StringPtr theSprileName. 

QTAtomContainer tbeActionAtome) 

l 

QTAtom rayPropertyAtoni; 

OSErr myErr = noErr; 

// set the sprite location data 

if (theLocation != NULL) { 

MatrixRecord myMatrix; 

SetIdentityMat rix {kmyMatrix) : 

myMatrix .matrix [2 ] [.0] = [(long)theLocation->h « 16): 
myMatrix.matrix[2][ll = [(long)theLocation->v « 16): 
EndianUt11s_MattixRecord_Nt oB(HmyMat rix}: 

myPropertyAtom = QTFindChildBy Index(theSprite, 
kParentAtoral^Container. 
kSpritePropertyMatrix. 1, HULL): 

If (myPropertyAtom = 0) 

myErr = QTInsertChild(theSprite. 

kFarentAtomlsContainer, 

kSpritePropertyMatrix. 1 T 0, 

sizeof(HatrlxRecortij, fcmyMatrix, HULL): 

else 

myErr = QTSetAtomData(theSprite. myPropertyAtom. 

slzeof(MairixRecord), &myMatrlx); 

If (myErr ! = noErr) 
goto bail: 

1 


// set the sprite visibility state 

if (theVisibie 1= NULL) ( 

short myVisible - *theViBible; 

myVisible = End ian S16. ,NtoB(my V i a i b 1 e) : 

myPropertyAtom = QTFindChildBy Ind ex (theSp rite f 
kParentAtomlaContainer, 
kSpritePropertyViflible- 1, NULL); 

if (myPropertyAtom — 0) 

myErr = QTInsertChild{theSprite, 

kParantAtomTsContainer. 
kSpritePropertyVisible. 1, 0, 
sizeof(short), fonyVisible. NULL); 

alia 

myErr = QTSetAtoinData(theSprite, myPropertyAtom, 
sizeof(short). fianyVisible): 

if (myErr 1= noErr) 
goto bail: 

] 

// set the sprite layer 
if (theLayer !- HULL) I 

short myLayer = *theLayer: 

my Layer ~= EndianS16_NtoB (myLayer) ; 

myPropertyAtom = QTFindChildBylndex(theSprite, 
k P a r enfAtomIsCo ntaine r. 
kSpritePropertyLayer, 1, NULL); 

if (myPropertyAtom = 0) 

myErr = QTInsertChild(theSprite, 

kFarentAtomlsContainer, 
kSpritePropertyLayer, 1 h 0, 
sizeof(short)* &myLayer t NULL); 

else 

myErr = QTSetAtomData(theSprite. myPropertyAtom. 

sizeof(short), &myLayer); 

if (myErr I- noErr) 
goto bail; 
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] 


// set the sprite image index 
if [theImageIndex E= NULL) f 

short inylmagelndex = * the I mage Index; 

my I mage Index = Endian-Si 6_HtpB (my Image Index); 

my P ro pert yAt om = QTFindChildBylndex(theSprite h 
kFarentAtomIsContainer, 
kSpritePropertyImagelndex, 1* NULL); 

if (myPropertyAtom = 0) 

myErr = QTInsertChild(theSprite, 

kPar an tAtomIs Coat a in e r, 
kSpritePropertylmagelndex, 1. 0, 
sizeof(short), &myImageIndex- NULL); 

else 

myErr - QTSetAtomData(theSprite, myPropertyAtom, 
sizeof(short). imyImageIndex); 

if [myErr != noErr) 
goto bail; 

} 


// set the sprite graphics mode 

if (theGr a phicsNod e 1= NULL) i 

ModifierTrackGraphiesModeRecord myGraphicsMode: 

myGraphicsHode.graphicsMode = 

EndianU32_NtoB CtheGraphicsHode >g,raphiesMode); 
myGraphicsMode.opColot.red * 

EndianUl6_ NtoB(fheCraphicsMode->opColor.red); 
ntyGraphicsMode.opColor .green = 

EndianUl6_NtoE(theGraphicsMode->opColor.green]; 
myGraphiesMode.apColor.blue 13 

EndianUl6^NtoB[theGraphicsMode->opColor.blue )* 

myPropertyAtom = QTFindChildEylndex[theSprite, 
kParentAtomlsContainer, 
kSprltePropertyGraphicsMode, 1, NULL); 
if (myPropettyAtotn “ 0) 

myErr = QTlOBertChild(theSprite t 

kParentAtomlsContainer * 
kSpritePropertyGraphiesMode. 1. 0* 
sizeof[myGraphicsHode), SmyGraphicsMode. 
NULL)j 

else 

myErr = QTSetAtomData[theSprite. myPropertyAtom. 

sizeof [myGrapli LcsMode), imyGraphicsMode); 

if (myErr I” noErr) 
goto bail; 


// set the sprite name 

if (theSpriteName 3= NULL) [ 

QTAtom mySpriteNameAtom: 

mySpriteNajmeAtom = QTFindChildByIndex(theSprite. 

kParent AtomI sContia j ne r + 
kSpriteNameAtomType. 1, NULL); 

If (inySpriteNameAtom = 0) 

myErr “ QTInsertChild(theSprite, 

kParentAtomlsContainer, 
kSpriteNameAtoraType, I. 0. 
theSpriteName[0] + 1. theSpriteName. 
NULL); 

else 

myErr = QTSetAtomData(theSprite. InySpriteNameAtom. 

theSpriteName[0] + 1. theSpriteName); 


if [myErr 3= noErr) 
goto bail; 


// set the action atoms 
if (theActionAtOtfiS t = NULL) 

myErr = QTInsertChildren[theSprite, 

kParentAt omlsContainer, 

t heActionAt oms): 

bail: 


if ((myErr J= noErr) && (theSprite t= NULL)) 
QTRemoveChildren(theSprite. 0); 

return(myErr); 


For each parameter that is not NULL, SpriteUtils_SefSpriteData 
looks to see whether the sprite atom container already contains 
an atom of that the corresponding type (by calling 
QTFindChildBylndex). If it does contain such an atom, then 
SpiiteUtils_Set3priteData calls QTSetAtomData to reset the data in 
that atom; otherwise, it calls QTInsertChild to add an atom of that 
type. In all cases, the data passed in Is converted to big-endian 
format before being inserted into an atom. 

Now that the mySpriteData atom container holds a child 
atom for each initial property we want to set, we need to add it 
to the key frame sample atom container, mySample. Once again, 
well define a utility function to help us out: 

SpriteUtils^AddSpriteToSample(mySample T mySpriteData, 
kQTIconSpriteAtomID): 


SpriteUtils^AddSpriteToSample is defined in Listing 5. 


Listing 5; Adding a sprite data atom to a sample container 

Kprird h iJs AddSprirt'To&mipte 

OSErr SpritelJtils_AddSpriteToSatdple 

(QT A totnCout ainer theSample. (JTAtomContainer theSprite, 
QTAtomID theSpritelD) 

QTAtom my SpriteAtom = 0; 

OSErr myErr " paramErr; 

// sec if Lite sample already contains a sprite atom of the specified [D 

mySpriteAtoin - QTFindChiId By ID[theSample, 
kParentAtomlsContainer* 
kSpriteAtomType, theSpritelD, NULL); 

If [mySpriteAtom J= 0) 
goto bail; 

// here, the index 0 means to append the sprite to the sample 

myErr = QTInsertChild[theSample* kParentAtomlsContainer, 

kSpriteAtomType, theSpritelD. 0. 0, NULL, 
firtnySpriteAtom) ; 

If [myErr 3“ noErr) 
goto bail: 

myErr * QTInsertChildren(theSample, mySpriteAton, 
theSprite): 


bail: 

return(myErr); 

] 


As you can see, SpnteUtiis_AddSpriteToSample first calls 
QTFindChildBy ID to determine whether the specified atom 
container already contains a sprite atom with the specified sprite 
ID. If there is an atom of that ID already in the sample, 
Sp rite Utils_AddSprrteToSampie returns an error to the caller. 
Otherwise, it calls QTInsertChild to create a sprite atom of that ID 
in the sample atom container. Then it calls QTInsertChildren to 
copy the children from the sprite atom container passed as a 
parameter into the newly inserted atom in the sample. 

Setting Sprite images 

So far* then, weVe created a sprite atom that contains the 
desired initial properties of the icon sprite and added it to the 
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key frame atom container mySample. Now we need to create an 
atom of type kSpriteSharedDataAtomType and add the required 
subatoms to it that contain the sprite image data. In the case of 
the icon sprite movie, we need to add two images to that atom, 
one for the old QuickTime extension icon and one for the new 
icon. The function QTSprites_AddlconMovieSamplesToMedia does 
this by executing these lines of code: 

myKeyColor.red = rciyKeyColor.green = rayKeyColor.blue = Qxffff; 

SpriteUtils_AddFICTImflgeToKeyFraiaeSample[mySample, 

kOldQTIconID. &myKeyCoior. 1. NULL, NULL); 

S p riteUti1 s_AddPICTTmageToKeyFrameSamp1e(mvSantple, 

kNevQTIconlD, fimiyKeyColor, 2. NULL. NULL); 

Once again, weTe relying on a function defined in the file 
SpriteUtilities.c to hide the nitty-gritty details of building the 
required atom from our main application, 
SpriteUtils_AddPICTImageToKeyFrameSampte (defined in 
Listing 6) reads a picture from our application’s resource 
fork, recompresses the picture with the specified color as a 
transparency color, and then adds it to the key frame sample 
atom container. 

listing 6; Adding compressed image data to a key frame 
sample 

Sprite tJtib_AddFlCTImageToKeyFrameSampte 

OSErr SpriteUtils„AddPICTImageToKeyFrameSamp1e 

(QTAtomCotit airier theKeySample, short thePictID. 

RGBColor ‘theKeyColor, QTAtomlD thelD, 

FixedPoint * theRegistrstionPoint, 

StringPtr thelmageName) 


PicHandle myPicture = NULL; 

Handle myCompressedPieture ■ NULL: 

IraageDestriptionBandle mylmageDesc = NULL: 

OSErr myErr = noErr: 

// get picture from resource 

myPicture = (PicHandle) GetPicture CthePictlD); 
if [myPicture = NULL) 
myErr = resNotFound; 

if [myErr != noErr) 
goto bail: 

BetacMesource [ (Handle)myPicture); 

// convert it to image data compressed by the animation compressor 

myErr = ICUtils_ReconjpressPietureWithTransparency 

trayPicture, theKeyColor, NULL, kmylmageBesc, 
krayCompressedPicture); 
if (myErr != noErr) 
goto ball; 

// add it to tire key sample 

HLoekfmyCompresaodPicture): 

myErr = Sprit eUtils^AddCorapressedlmageToKeyFrame Sample 
(theKeySample. mylmageBesc, 

GetHaridleSize(ayCompressedPicture), 
^myCompressedPicture, thelD, theKegistrationPoint, 
thelmageName); 

bail: 

if [myPicture ! = NULL) 

KillPicture(myPicture); 

if (myCompresaedPicture != NULL] 

DisposeHandle(myCompressedPleture): 

if fmylmageDesc != NULL) 

DisposeHandle((Handle)myIraageDesc): 

return[myErr); 
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SprteUtils_AddPICTimageToKeyFrameSampie does most of its 
work by calling two other utility functions, 
ICUtiis_RecompressPictureWithTransparency and 

SpnteUtils_AddCompressedlmageToKeyFrameSairiple. We wont 
dissect either of these functions in detail here, as that would take 
us too far afield, Sp rite Utils_AddCom pressed I mageToKeyFrameSam pie 
really just does what you'd imagine to build the atom container 
illustrated in Figure 7. 

Adding the Key Frame Sample to the Sprite Media 

So, we've managed to build the key frame sample. Now we 
just need to add it to the sprite media. To do diis, we first need 
to create a handle to a sprite sample description, which well 
pass to AddMediaSample. A sprite sample description is defined 
by the SpriteDescriptton data type, declared like this: 

struct SpriteDescription [ 


long 

descSlze; 

long 

dataFotmat; 

long 

resvdl: 

short 

resvd2; 

short 

dataReflndex; 

long 

version; 

OSType 

decompressorType: 

long 

sampleFlags; 


I; 

We allocate a handle to a sprite sample description by calling 
NewHandleClean 

loySampleDeac “ (SampleBes^riptioftHandle) 

NevHandleClearCsizeof(SpriteDeacriptlon]}; 


The decompressorType Odd of the sprite sample description 
specifies the type of compressor used to compress the sample 
data (or 0 if no compression is used). The sprite media handler 
supports compressed sample data; the only restriction is that the 
compressor used to compress the data must be lossless. {A 
compressor is lossless if the result of compressing some data and 
then decompressing it yields the original data unchanged; 
otherwise, the compressor is lossy,) For the moment, we’ll just 
use tlie uncompressed data diat we’ve created. So we can just 
go right ahead and call AddMediaSample: 

tnyErr = AddMediaSample(theMedia, (Handle}mySample, 0, 

GetHandleSize(mySample). kSpriteMediaFraJneDurationlcon, 
my SampleDess. 1*0, NULL]: 

We can use yet another utility function defined in 

SpriteUtilities.c: 

SpriteUtils_AddSpriteSamp]eToMedia(theMedia, mySample t 

kSpriteMediaFrameDurationlcon, true, MULL); 

Listing 7 shows our definition of 
SpriteUtils^AddSpriteSampleToMedia. 

Listing 7: Adding a sprite sample to the sprite media 

S pritc t 1 lils_Adds p ri teSampleTo M e dia 

OSErr SpriteUtils_AddSpriteSainpleToMedia (Media theMedia. 

QTAtomCdntalner thcSample. TimeValue theDuration, 
Boolean isKeyFrame. TimeValue ^theSampleTime) 

I 

Sampleft.escriptionHandle mySampleDesc = NULL: 

OSErr myErr = noErr; 
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mySaJnpleDesc = (SampleDescriptianlialidle) 

NewHandleClear (eizeof[SprfteDescription)); 
if (raySainpieDesc = NULL) [ 
myErr = MemError() ; 
goto bail: 


myErr = AddMediaS amp1e(theMedia, 

( Handle) theSample. 

a* 

GetHandleSizs (theSample]* 

theDuration* 

mySampleDesc, 

1 * 

(short)(isKeyFrame 7 0 : mediaSampleNotSync)* 
theSampleTinie); 

bail: 

if (mySampleDesc 1= NULL) 

DisposeHandle( (Handle) lnySampleDesc) : 
return (myErr); 

] 


Note that SprrteUtils_AddSpriteSamp!eToMedia adds the 
specified sample data as a key frame sample or an override frame 
sample, depending on the value of the isKeyFrame parameter, 

Creating Override Samples 

Willi these sprite utility functions at our disposal, it’s now 
quite easy to create some override samples and add them to the 
sprite media. For the icon movie, we want to create 99 override 
samples. Each override sample will move the icon 2 pixels to the 
right; furthermore, when the icon reaches the halfway point, 
well change the image index from 1 to 2. Listing 8 shows the 
code we use to add those override samples to the sprite media. 

Listing 8: Adding some override samples 

QTSprttcs^AddlconMovfcSomplesToM cd in 
for CmyCount = 1: my Count kNumOVerrideSaiiples: nyCount+F) 

I 

QTRemoveChlId r en (my Samp1e, kPa r e ntAtamisContainer); 
QTRemoveChildrenCmySpriteData. kParentAtonleContainer): 

// every frame, hump the icon’s location 

myLocation.h -N 2: 

// change icon half way tliru 

if (myCount = kNumOverrideSamples / 2) 
myIndex = 2; 

SpriteUtiIs_SetSpriteDatfl(mySpriteData, fanyLocation, NULL. 

NULL* Index, NULL. NULL. NULL): 
SpriteUtils_AddSpriteToSampie (mySample T nrySpriteData, 
kQTIeanSpriteAtnmlDJ; 

SpriteUtils_AddSpriteSampleToMedia(theMedia* mySample* 

kSpriteMediaFrajneDurationlcon. false* NULL); 


Setting Sprite Track Properties 

We saw earlier that we can use a sprite image as the 
background of a sprite track by setting the layer of the image to 
kBackgroundSpriteLayerNuru, But what if we want to have a solid 
background color for the entire sprite track? We could of course 
create a sprite image of the proper size and color and then put 
it into the first key frame sample of the sprite track. The sprite 
media handler, however, provides a better method to set a solid 
background color by allowing us to set the sprite track’s 


background color property. The background color property is 
one of several sprite track properties that control global aspects 
of the sprite track. The currently defined sprite track properties 
are accessed using these constants: 

enum [ 

kSprite-TrackPropertyBackgroundColor = 101* 

kSpriteTrackPropertyQffscreeriBitDepth = 102* 

kSpriteTrackPropertyS amp1eFo mm t =103* 

kSpriteTrackPropertyScaleSpritesToScaleUorld 

= 104* 

kS p rit sT rack? r ope rtyHasAc11ons = 10 5 * 

kSpriteTrackPropertyVifcibie = 106* 

kSpriteTrackPropertyQTIdleEventsFrequency - 107 

): 

To set one or more sprite track properties, we need to 
create a media property atom , an atom container dial contains a 
child atom for each of the properties we want to set. The atom 
type of the child atom should be set to one of these sprite 
property constants, and the atom ID should be set to 1. The type 
of the atom data varies from property to property. For the 
background color sprite track property, the atom data is an 
RGBColor structure. Once we’ve constructed the media property 
atom, we attach it to the sprite track by calling the 
SetMediaPropertyAtom function. Listing 9 shows how we set a 
solid white background for the penguin sprite movie. (If we 
don’t specify a background sprite image and we don’t set the 
background color property, then we’ll get the default sprite track 
background color, which is black.) 

Listing 9: Setting the background color of a sprite track 

QTSpri Ecs_SetTrackPropeni« 

void OTSprites^SetTrackProperties (Media theMedia, 

Hint16 theMenuItem) 

I 

QTAtontContainer myTrackPropertiea; 

RGBColor myHa c k g rou nd Co1or; 

QSErr myErr = noErr; 

if (IgUseBackgroundPictvtre) l 

H add a background color to the sprite track 

QTSpr11 es_Ge tBac kg r o undC o1o r(t heMenuItem* 
&myBackgroundColor); 

myErr = QTNewAtomContainer(imyTraekPropetties); 
if (myErr = noErr) I 

QTInsertChild(myTrackFropertiea, 0. 

kSpriteTrackPropertyBflckgroutidColor, 1* 1, 
sizeof [RGBColor) * kiayBackgroundColor, 

NULL): 

SetMediaPropertyAtomftheMedia, rayTrackProperties); 
QTDisposeAtomContainer (tnyTrackPrcpertles) ; 

1 

\ 

1 

The kSpriteTrackPropertyOffscreenBitDepth property 
specifies the desired bit depth of the offscreen graphics world 
where the sprite data is drawn before it is copied to the 
screen. The atom data is of type short, and the default value 
is 0 (w hich means to use the bit depth of Lhe deepest monitor 
that intersects the onscreen sprite window). Setting this 
property can save memory if your sprite graphics are drawn 
at a lower bit depth than the user’s monitor. 

The kSpriteTrackP rope rtySam pie Format property specifies the 
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override sample interpretation mode, which indicates how the 
sprite media handler interprets override samples. Currently there 
are two possible modes: 

ermra { 

kKeyFrameAndSingleOverride = 1L 4< 1, 

kKeyFtameAndAllOverrides = 1L « 2 

3; 

If the override sample interpretation mode is 
kKeyFrameAndSmgleOverride. then the sprite media handler 
generates the sprite data for a particular override sample by 
applying the changes in that override sample directly to the 
key frame sample, ignoring any previous override samples, 
(This is the default mode,) On the other hand, if the mode is 
kKeyFrameAndAIIOverrides. then the sprite media handler 
generates sprite data by applying the changes in a particular 
override sample to the data generated by applying the 
changes in ad previous override samples to the key frame 
sample data. In other words, kKeyFrameAndSingleQvemde 
specifies that a particular override frame contains absolute 
changes to key frame data, while kKeyFrameAndAIIOverrides 
specifies relative changes. 

The kSpritelrackPropertyScafeSpritesToScaleWoHd property 
specifies whether the sprites in the sprite track are rescaled 
whenever the sprite track is resized This is useful mostly when 
the sprite images have been compressed using a resolution- 
independent codec (for example, the Curve codec). The atom 
data is of type Boolean, and the default value is false. 

The kSpriteTrackProperty Visible property specifies 
whether the sprite track is visible. The atom data is of type 
Boolean, and the default value is true. It might occasionally 
be useful to set the sprite track to be invisible if there are 
other tracks in the movie and you want to allow the user to 
click on items in those tracks (by putting an invisible sprite 
track in front that intercepts those clicks). 

The remaining two sprite track properties apply only to 
sprite tracks that contain wired actions. The 
kSpriteTrackProperty Has Actions property specifies whether the 
sprite track contains any wired actions; the atom data is of 
type Boolean and the default value is false. The 
kSpriteTrackPropertyQTIdleEventsFrequency property indicates 
the desired frequency at which the sprite media handler 
should send idle events (events of type kQTtdle Event) to the 
sprite track. In this case, the atom data is of type Ulnt32 and 
the default value is kNoQTIdleEvents (which means not to 
issue any idle events). Well consider these two sprite track 
properties in more detail in our article on wired sprites. 

Putting it AO Together 

Let’s see what the tw'o functions 

QTSprites AddlconMovleSamplesToMedia and 

QTSprites_AddPengmnMovieSamplesToMedia look like in their 
entirety. Listing 10 shows the definition of 
QTSprites AddlconMovleSamplesToMedia. 
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Listing 10; Adding samples to the icon ; 

QTSpritcs_AddJconMovirfamplesToMcdm 
void QTSprites_AddIconMavieSamplesToMedia (Media theMedia) 


QTAtomContainer 

QTAt omC ontainer 

RGBGolar 

Point 

sho rt 

short 

OSErr 


mySample = NULL; 
tnySpriteData = NULL: 
my Key Color: 
rayLocation; 
isVisible; 

myLayer. myltidex, myCmmt; 
myErr - noErr; 


// create a new, empty key frame sample 
myErr = QTNewAtomContainert&mySample): 
if (myErr 1= noErr) 
goto bail; 

myKey Color *red = myKey Color, green = myKeyCo lor* blue " 

Oxffff; //while 


// add images to the key frame sample 

SprlteUtils_Add PICTIm ageToKeyF rameS amp1e£myS ample. 

kOl dQTI conit). AmyKeyColor H 1, NULL. NULL); 
SpriteUtils_A^dPICTImageToKeyFrameSample[roySample. 

kNewQTIconID* MnyKeyColor t 2, NULL, NULL): 

// add the initial sprite properties to the key frame sample 

myErr = QTNewAtomContainer(AmySpriteData); 
if (myErr t= noErr) 
goto bail: 

// the QT icon sprite 

myLocation-h “ 32 ; 
pyLocation.v = 32: 

IsVisible * true; 
myLayer & -1; 

my Index = 1; 

SpriteUtlls .SetSpriteDataCmySpriteData, AmyLocation, 

fiiisVisibie. AmyLayer* Araylndex. NULL. NULL. NULL): 
S p r 1teUtils_AddSp riteToSamp1e(mySample * mySp riteData* 
kQTIconSpriteAtomlD); 

SpriteUtils_AddSpriteSampleToHedla[theMedia* mySample. 
kSpriteMediaFraineDiirationlcon* true. NULL); 

// add a few override samples to change the icon's location and image 

for (myCount - 1; myCount <- kNumOverrideSainples; 
myCount++) [ 

QTRemoveChildren(mySample. kParentAt omlsContainer); 
QTRomoveChi Id ren (mySp r 1 tefJata, kPa rentAtoml sContainer): 

//every frame,bump the icon's location 

myLocation.h += 2; 


// change icon half way thru 

if (myCount = kNumOverrideSamplGS / l) 
my Index * 2: 


1 


SpriteUtils_SetSpriteUata£mySpriteData, AmyLocation, 
NULL, NULL, &myIndex. NULL. NULL* NULL): 
SpriteUtils_AddSpriteTaSampie(mySample. tnySpriteData, 
kQTlconSpriteAtomlD); 

SprlteUtil s_. Add SpriteSample ToMedia(t he He dia t myS amp1e * 
kSpriteHediaFrameDurationlcon. false, NULL); 


bail: 

if (mySample NULL) 

QTDisposeAtomContainer(mySample); 

if (mySpriteData != NULL) 

QTDiaposeAtotnContainer {mySprit eData); 
I 
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Listing 1 ] shows our complete definition of 

QTSprites_AddPenguinMovieSamptesToJVledia. 


Listing Us. Adding samples to the penguin sprite movie 

QTSprites_AddPenguMMovieSampleiToMcdla 
void QTSprites_AddPettguinMovieS£nple&ToMedia (Media theMedia) 

I 

QT AtoraContaine r jnySample - MULL: 

QTAtomContainer mySpriteData = NULL: 

RGBColor myKeyColor; 

Point myLocation: 

short isVisible: 

short myLayer, myIndex, myCount; 

ModifierTrackGraphiosModeRecord 

tnyGraphfcsMode; 

OSErr myErr =* noErr; 

// create a new, empty key frame sample 

myErr = QTNerwA 1 tomContainer(&mySample); 
if (myErr f~ noErr) 
goto bail: 

myKeyColor,red = myKeyColor,green “ myKeyColor,blue ” 

Oxffff; // white 

H add images to the key frame sample 

SpriteUtils_AddPICTIniageToKeyFrameSample [my Sample, 
kPengti1nPictlD» &myKeyColor t 
kPenguinlmagelndex, NULL, MULL); 

U add the initial sprite properties to the key frame sample 

myErr “ QTMewAtoinContainer UanySpritaData): 
if (myErr J* noErr) 
goto bail: 


// the penguin sprite 

jnyLocation.h = 0: 
myLocation.v = 0; 
isVisible = true: 
myLayer 3 - 1; 

my ltd ex = 1; 

// sci the initial blend amount (0 s fully transparent; Oxffff = My opaque) 

myGraphicsMode.graphicsModo = blend: 
ioyGraphicsMode.QpColor.red = 0: 
myGraphicsHode.opColor,green = 0; 
myGraphicsMode.opColor.blue = 0 ; 

SpriteUtils_SetSpriteData(mySpriteData, &myLocation, 

iiaVisible, JunyLayer. itfnyIndex, imyGraphicsMode, 
NULL, NULL): 

SpriteUtils_AddSpriteToSarap 1 e [mySamplemySpriteData. 
kPengninSpriteAtomlD): 

SpriteUtiIs_AddSpriteSatnpleToMedia(theMedia , mySamp1e, 
kSpriteMediaFrameDurationPenguin, true, NULL): 

// add a few override samples to change the penguin's opacity 

for (myCount = 1; myCount <= kMumOverrideSansples: 
ToyCount ++ ) [ 

QTRemoveChildren (mySample. kParentAtoml sContainer); 
QTReuioveChildren(mySpriteData, kParentAtomlsContainerJ; 

// ever) frame, bump the penguin's opacity 

myGraphicsMode.graphicsMode ~ blend: 
myGraphicsMode.QpColor.red = (myCount - 1) * 

(Oxffff I kNumOverrideSamples - 1) 
myGraphicsMode.opColor.green = (myCount - 1) * 

[Oxffff / kNuroQverrideSamples * 1) 
myGraphicsMode.opColor.bliie = {myCount I) * 

(Oxffff / kNumOverrideSamples - 1) 
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and modules. 
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SpriteUtils.SetSprireDatafmySpriteData, MULL, HULL, NULL* 
NULL, imyGraphicsNode. NULL, NULL); 
SptiteUtils_AddSpriteToSample(mySample. tnySpriteData„ 
kFen&uinSpriteAtoralD); 

SpriteUt ils_AddSpriteSamp1eToMedia{theMedia * my Samp1e, 

kSpriteMediaFrameDurationPenguin, false* NULL): 


bail: 

If (mySample != NULL] 

QTDispos eAtomCont aine r(myS amp1e )\ 

if (mySpriteData != NULL) 

QTDisposeAtomContainer{mySpriteData); 


For the definition of 

QTSprite$_AddSpaceMovieSample$ToMedia, see die file QTSprites.h, 
The basic strategy is the same, but the increased complexity of the 
space movie gives a considerably longer function. 

Hit Testing 

As 1 mentioned earlier, QuickTime sprites can be 
interactive. That is to say, we can create movies with sprite 
tracks whose sprites respond to user actions like mouse 
movements and mouse button clicks. When we consider wired 
sprites in a future article* well investigate the full power of this 
interactivity. In the meantime, let's take a look at a more 
limited form of interactivity supported by non-wired sprites, 
the ability to determine whether the user has clicked on a 
sprite (also called hit testing). 

Programmatically finding dicks on a sprite is a two-stage 
process. First, we need to determine when the user has clicked 
the mouse button inside of the movie rectangle. Then we need 
to determine whether that mouse click was on top of a sprite. 
For the first task, we can add a case to the switch statement in 
our movie controller action filter function 
QTApp_MCActionFiiterProc, looking for the me Action Mo use Down 
movie controller action (as shown in Listing 12). 


Listing 12: Detecting clicks in the movie window 


switch (theActlon) I 


QTApp _ MGActionFiltcrProc 


// handle window resizing 

case racAc 11onControl1erSizeChanged: 

QTFramejSizeWindDWTaMavie(myWindowObject): 
break; 


// handle idle events 

case mcActlonldle: 

QTApp_Idle( (^myWindowObJect) * fWlndow); 
break: 


// Ira nd If moustnlnwn events 

case meActi&nMouseDown: 

isHandled ■ QTSpritesJiitTestSprttes(myWindowCbject. 

(EventReccrd *)theFarams): 

break; 

default: 

break; 

I 


The movie controller issues an mcAction Mouse Down action 
whenever it receives a mouse-down event that’s inside die movie 
rectangle. The parameter data passed to our action filter function 
(in theParams) is a pointer to the event record for that mouse- 
down event. As you can see, our filter function simply calls the 
application-defined function QTSprites_HitTestSprites to see 
whether the dick is on a sprite and, if so, to react appropriately* 
(For more information about movie controller action filter 
functions, see “QuickTime 10 r in MacTech, January’ 2000 .) 

The sprite media handler supplies die 
SpriteMedlaHitTestOneSprite and SpriteMedlaHitTestAIISprites 
functions* which w r e can use to determine whether the user has 
clicked on a sprite. For present purposes, well use 
SpriteMediaHitTestANSprites, which looks at each one of the 
sprites in a sprite track to see whether it is currently at a 
specified location, SpriteMedlaHitTestAIISprites is declared 
essentially like this: 

ComponentResuit SpriteMedlaHitTestAIISprites 

(MediaHandler tnh. long flags, Point loc. 

QTAtomlD ‘spriteHitlD)j 


If a sprite is situated at tile specified location in die sprite track 
associated with the specified sprite media handler* then 
SpriteMedlaHitTestAIISprites returns the ID of dial sprite in die 
spriteHitlD parameter. If more dian one sprite is situated at that 
location, then spriteHitlD is set to die ID of the frontmost sprite (that 
is, the sprite with the lowest layer number). If no sprite is situated aL 
that location* then spriteHitlD Is set to 0. 

By default, the loc parameter should tie die location of the 
mouse click, in coordinates local to die sprite track However, the 
event record passed to our movie controller action filter function 
contains the location of the mouse click in global coordinates. Rather 
than lx idler widi converting die global location to a local position, 
we can add spriteHitTestloc In Display Coordinates to the flags 
parameter* to indicate dial die loc parameter is in global coordinates. 
These flags are understcxxl by SpriteMediaHitTestAliSprites: 

em m l 

SpriteHitTestBounds " IL << 0* 

spriteHitTestImage = IL << 1* 

spriteHitTestlnvisibleSprites = IL << 2. 

sprltaHitTestlsCilck = IL « 3* 

sptlteHitTestlocInMsplayCoordimtes = IL « 4 

Is 

If you want to accept dicks anywhere within the rectangular 
Ixxtnding lxix of a sprite, add in the spriteHitTestBounds flag. If* 
conversely, you want to accept dicks only on a non-transparent part 
of a sprite, add in the spriteHitlestlmage flag. You must specify one 
or the other of these two flags, or else no hit-testing will occur. 
Setting both of these flags is tantamount to setting only 
spnteHitTestlmage. (Earlier versions of QuickTime required you to set 
lx ah flags if you wanted image testing, but current versions do not*) 
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By default, SpnteMediaHitTestAIISprites and 
SpriteMediaHEtTestGneSprite Lest only visible sprites for hits. II' you 
want to test invisible sprites as w ell set the spriteHitTestlnvisibleSprites 
flag. If you want to pass the mouse dick onto the codec that is 
rendering the sprite image, then specify the spriteHitTestlsClick flag; 
this is currently useful only with the Ripple codec 

In GTSprites_HitTestSprftes, we want to test both visible and 
invisible sprites for hits, and we want to test only within the non¬ 
transparent portions of a sprite image. So we’ll specify our flags 
parameter like this: 

myFlags = spriteHitTestImage | 

spriteHitTestLocInDisplayCoordinates | 
spriteHitTestlnvisibleSprites; 


Now, what will we do when we detect a dick on a sprite? In 
theory, we can do anything we want We’ve got die entire 
QuickTime AIT at our disposal, so we could do some neat tilings 
like launch the users web browser and navigate to a specific page, 
or download a file from a remote location, or even build a 
QuickTime movie. Even just within the context of our sprite track 
we could do some rather interesting stuff, like moving die sprite to 
a new location in die sprite track, changing its image index, and .so 
forth. For simplicity, well limit ourselves to changing the sprite’s 
visibility state: if the sprite is currently visible, well make it invisible 
(and vice versa), 

SpriteMediaGetSpritePropertyimyHandler, myAtomlD, 


IcSpritePropertyVisible t (void *)kisVisible): 
SpriteMediaSetSpriteProperty(myHandler t myAtomlD, 

kSpritePropertyVisible* (void *)lisVisible); 


Listing 13 shows our complete definition of 

GTSprites_HifTestSprites, 


QT$prites_HUTestSprites 

Boolean QTSprites_HitTestSprites 

(WindowObject theWindowGbject. Event Record *the.Event) 

( 

ApplicationDataHdl myAppData - NULL: 


MediaHandler 
boolean 
long 

QTAtomlD 

Point 

ComponentResult 


myHandlet = NULL; 
isHandled = false; 
myFlags = QL; 
myAtomlD = 0; 
myPoint: 
inyErr = noErr: 


myAppData - (ApplicatlonDataHdl) 

QTFrame_GetAppData?romWind owObject{theWindowObj act ) ; 
if (myAppData = NULL) 
goto bail; 


if (theEvent = NULL) 
goto bail: 


// miikc sure that the dick is in our window 
if ((**1hfitf1 1 ulowOb j ec t1 f fWindow J“ 

QTFraroe_GetFtontMovieWindow()) 

goto bail: 


myHandler = (*'myAppData).fSpriteHandler; 
myFlags _ spriteHitTestImage | 

spriteHitTestLpcInDisplayCOGrdinfltBs | 
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spriteHitTestlnvisibleSprites: 
myPoint = theEvetit->where: 

rayErr = SpriteHediaHitTeetAll Sprites [myHandler. myFlags. 

myPoint„ imyAtotalD}; 

if ((myErr “ noErr) && [myAtomID 1= 0)) [ 

Boolean isVisible; 

// the user hits clicked on a sprite; 

// for now, we ll just toggle the visibility state of the sprite 

SpriteMediaGetSpriteProperty ImyHandler * tnyAtomlD „ 
kSpritePropertyVisible, (void 

*)&isVisible) : 

SpriteMediaSetSpriteProperty(tnyHandler, myAtomlD, 
kSpritePropertyVisible, (void 

*)IisVisible); 

isHandled = true; 

I 

bail; 

return(isHandled); 

I 


You’ll notice that we need to make sure that the window 
associated with the window object passed to 
QTSpritesJHitTestSprites is die frontmost movie window, by 
executing these lines of code: 

If t(*HhetfindowObject).fWIndow 1= 

QTF rame_Get F r o nt MovieWindow()) 

goto bail; 

Hi is is Ixxause, when we are handling an event on Macintosh 
computers, we culJ MClsPlayerEvent Ibr each open movie controller, 
until we find one that handles the event. It's possible to have two or 
more overlapping sprite movies such that a mouse click does not hit 
a sprite in the frontmost movie window but does hit one in an 
overlapped window. We am avoid unexpected behaviors by 
limiting our hit testing to the frontmost movie window* (On 
Windows, this additional check is unnecessary but harmless.) 


Conclusion 

In this article, we've seen how to create and work with sprite 
tracks in QuickTime movies. Sprite tracks are remarkably easy to 
create* It’s really just an exercise in creating atom containers and 
adding them as samples to a sprite media. Keep in mind that sprite 
media data isn’t just a collection of pixels that are copied from the 
movie file onto the screen. Rather, sprites are distinct objects, with 
properties that can lx* changed dynamically to animate the sprites. 
This is what accounts for the drastic size differences between sprite 
and non-sprite versions of a movie* This is also what accounts for 
our ability to interact with individual sprites (for instance, our ability 
to hit test mouse dicks on sprites)* 

in the next article, we’ll continue our investigation of sprites. 
Among other things, well see how to use a video track as the source 
of a sprite’s image data, and well see how to use modifier tracks to 
animate sprites. Believe it or not, using modifier tracks instead of 
override samples will result in even further size reductions for our 
sprite movie files. Slay tuned! 

Acknowij^fjwents and References 
The utilities in the file SpriteUtilities.c were originally written by 
Sean Allen; 1 have taken the liberty of reworking them to bring the 
general programming style into conformance with the rest of the 
sample code we’ve encountered in this series of articles, The code 
for building the space movie is based on an existing sample code 
package, MakeSp rite Movie, c, also by Sean Allen. 

The definitive API reference for QuickTime sprites and 
wired actions is the book QuickTime Wired Movies And Sprite 
Animation by Tom Maremaa (downloadable from 
http://developer.apple.com/techpubs/quicktime/qtdevdoG/RM/pdfframEhfm), 
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Carbon: An 
Element of 1 

Essential 

Mac OS X 


O ne of the things that makes Mac OS X unique is its 
integration of five separate application runtime 
environments: Carbon, Cocoa, Classic, Java, and BSD. 

Never before has an operating system offered developers so many 
options. This series of articles will give you the information you 
need to make an informed decision as to which of these 
environments is right for your application on Mac OS X. This month. 
I’m going to talk about Carbon and what it offers you as a Macintosh 
developer. 

A Brief History of Carbon 

Carbon represents the evolution of the Mac OS API, from a single- 
user, cooperatively scheduled system, to a modern multi-user system 
with memory protection and preemptive multitasking. Carbon 


ADC Programs 
and Mac OS X 

A s Steve Jobs, Apple's CEO, announced at Macworld 
San Francisco in January, Mac OS X will be released 
on March 24, 2001. All ADC Members who receive a 
monthly mailing will be automatical fy sent Mac OS X and 
the Mac OS X Developer Tools on CD-ROM upon release. 

If you are getting your hardware or software products 
ready for Mac OS X, be sure to take advantage of our 
numerous ADC Member Discounts for Cocoa and Carbon 
porting, Aqua integration, driver development services, 
and more. Mac customers will be looking for hardware 
and software products that are built for Mac OS X - make 
sure yours are ready! For the complete list of all ADC 
Member Discounts, please see: 
http://devetoper.apple.com/business/ 

For more information about ADC Programs, please see: 
http://developer.appto.com/membership/ 


sprang from Apple’s desire to provide a 
gentle migration path for developers, while at 
the same time delivering all the performance, 
features, and reliability that Mac OS X has to 
offer About 70 percent of the classic Mae OS 
APIs are hilly supported, and Carbon adds 
many new APIs specifically to take advantage 
of Mac OS X. 

What Diamonds 
Are Made Of 

Carbon offers a wealth of features to support and accelerate your 
Mac OS X development efforts. Whether you're new to the platform, 
or an old-timer, here are some of the reasons why you’ll find Carbon 
a solid foundation for your software product: 

* Brood Language Support 

Apple provides interfaces* compilers, and tools for Carbon 
programming in C and C+ + , while other languages such as 
BASIC and FORTRAN are offered by other tool vendors. 

* Excellent Tools 

As we covered in last month’s article, Tools for the Trade , you 
can choose from a range of excellent tools including Metrowerks 
CodeWarrior, Real Software’s REALbasic, Absoft Pro Fortran, and 
Apple’s own IDE combo, Project Builder and Interface Builder. 

* Choice of Frameworks 

The two most popular object-oriented application frameworks 
for Macintosh are now Carbonized: MacApp (part of Apple's suite 
of C+ + frameworks) and Metrowerks PowerPlant (version 2.1 or 
later). Basing your application on one of these frameworks can 
greatly simplify your work. 

* Support for Mac 05 9 

Because the majority of Carbon APIs are also supported on Mac 
OS 9, Carbon provides a solution to the problem of how to move 
forward with Mae OS X while continuing to support those people 
who are going to wait a bit longer to upgrade. If backward com¬ 
patibility is important for your product, you can create a single 
binary that will run on any version of the Mac OS, from Mac OS 
8.1 through Mac OS X. 



Mark Turner is the Carbon Technology Manager in Apple Worldwide Developer Relations, When he's not Carbonizing code , he enjoys carbonizing ham¬ 
burgers on the grill and spending time with bis family He can be reached at turmr@appk.com. 
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Getting Started 

If you're smiting from scratch, and you want to program in C or 
C++, you should really consider basing your Carhon application 
on a framework like PowerPoint or MacApp, which provide for rapid 
development and easy maintenance. These frameworks can also 
make it easier to port your code to or from the Microsoft Win32 
API, if that's a consideration for you, REALbasic and Absoft Pro 
Fortran also offer cross-platform solutions* 

For an excellent introduction to Carbon programming, grab a 
copy of Moon Travel Tutorial; Creating a Carbon Application. This 
little gem takes you through the entire process of building a pure 
Carbon app—one that doesn’t rely on any legacy technologies. 

You'll also learn how to use Apple’s Project Builder IDF, and see 

how easy it is to design your menus, controls, dialogs, and windows 

using Interface Builder. You can download it from: 

http: I/developer, apple, com/tecbpubs/m acosx/Carbo n/pdfl 

MoonTmvelpdf 

The best place to begin exploring Carbon is the Carhon Developer 
home page, where you’ll find links to the latest Carbon software 
development kits, documentation, tools and other resources: 
http;!/developer, applexom/macosx/carbon/ 

If you've already got a Macintosh application that you haven’t yet 
Carbonized, it's time to get started! One of the great things about 
Carbon is that you can adopt it incrementally. The basic steps 
necessary to get an application up and running on Mac OS X 
ty pically take just a few days, but to completely Carbonize a large 
application you should expect to spend a month or more, especially 
if you need to support Mac OS 9 or prior versions* 

The ease of Carbonizing an existing application is directly 
related to how closely you've followed Apple’s recommended 
programming practices in the past, the degree to which you’ve 
adopted recent APIs such as Navigation Services and the 
Appearance Manager, and whether your code already compiles 
using the latest Universal Interfaces. If your code base is up-to-date, 
and you’re not relying on undocumented data structures or 
unsupported features, adopting Carbon is relatively simple. 

Before changing a line of code, however, you should run your 
application through Carbon Dater, Apple's Carbon compatibility 
tester Available on the Carbon Developer web site, Carbon Dater is 
a helpful tool that examines your application and Issues a report 
listing all the Mac OS functions you’re using that need to be 
updated for Carbon compatibility. For example, if you're calling 
InvalReet, the report will explain that the function is not supported 
in Carbon, and recommend that you use InvaJWindowRect instead. 

With the Carbon Dater report as your guide, you can begin the 
Carbonization process by searching your sources for unsupported 
functions and replacing them with their Carbon equivalents. While 
I can’t cover the entire Carbonization process in detail here, you’ll 


find a complete description in the Carbon Porting Guide , which 
you can download from here: 

http://developer, apple. com/tecbpubs/macosx/Carbon/pdf/ 

Ca rbonPortingGuule.pdf 

Even if you’re not porting, I recommend reading the Carhon 
Porting Guide for its overview of new Carbon technologies, 
optimization strategies, and instructions for building Carbon 
applications using CodeWarrior, Project Builder, and the Macintosh 
Programmer's Workshop (MPW ) , Technical Note 2003: Moving Your 
Code to Mac OS % is anodier great resource. It highlights all the 
major considerations for developers transitioning from classic Mae 
OS to Carbon, and provides pointers to additional documentation 
on the web: 

http: i! developer, apple. comitechriotes/tn/tn2003. him! 

Once your application is Carbonized, you’ll want to make sure it 
looks great on Mac OS X. This means putting the polish on your 
interface by giving it an Aqua tune-up. The Aqua Human Interface 
Guidelines contains all the specifications and recommendations for 
designing Aqua-compliant applications and icons: 
http: //developer apple, coni/techpubs/macosx/System Overview/ 
AquaCuidelines.pdf 
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Project Builder 
Tips & Tricks 

* To get a pop-up menu containing afl the functions in 
your source files, select “Index Project” from the Project 
menu. This also enables definition searches from the 
batch find panel. And, the counterpart button (the third 
button from the right in the navigation bar) becomes a 
pop-up menu that shows files that are imported by or 
dependent on the current file. 

* The inspector panel, available from the Project menu, can 
be used to modify more than one file at a time. For 
instance, if you want to set the tab width for a number of 
files all at once, select them in the Groups and Files pane, 
bring up the Inspector, change the tab width, and hit return, 

* To set a breakpoint on a line of code, just click in the 
column to the left of that line of code. Clicking again 
enables and disables the breakpoint. To remove the 
breakpoint, drag it off the column* You can also move a 
breakpoint to a different tine by dragging it. 

* To rename a file or group, option-click its name from 
the Groups and Files pane. 







New Mac OS X 
Related Releases 

The following software is available from die Download Software 
area of the ADC Member Site at: 
http: if connect, apple, com/ 

• CarbonLib 1.2.5b2 SDK 

The latest prerelease version of the CarbonLib 1.2.5 software develop¬ 
ment kit provides all the files needed to begin Carbon development, 
http:!!connect, apple, com/ 

• OpenGL SDK L2 

This software development kit is for adding OpenGL support to 
your application. This implementation provides several features and 
performance enhancements, 
http; I/developer, apple, com/opengl/downloads, btm l 

Developer Documentation 

The following new and updated documentation is available to help 
you on your way to successful Mac OS X application and peripheral 
development at: 

http://developeKapple.com/tecbpubs/ 

• Q&A OA 10(H) - Gathering system information under 
Traditional Mac OS 

• SAMPLECODE - Graphics 3D: Carbon SetupGL 

• SAMPLECODE - Graphics 3D: OpenGL Movie 

• SAMPLECODE - Platforms and Tools: Project Builder: 
Coeoa_With_Carbon_or_C + + 

• SAMPLECODE-Networking: OTStreamLogViewer 

• SAMPLECODE - Networking: OTClassicContext 

• SAMPLECODE - Devices and Hardware: Drivers: 
TradDriverLoaderLib 

Mac OS X: An Overview for Developers 

This 10-page PDF highlights the benefits of Mac OS X technologies 

to developers. 

http://developenapple.com/macosx/ 

FatbraiiTs Apple Developer Library 

The following four titles have been added to the Apple Developer 
Library, the ADC’s print-on-demand series of Lilies located at: 
http://wwuflfiithmin.com /applel 

• Carbon Porting Guide for Mac OS X 

• Inside WebObjects: WebObjects Overview r 

• Inside Mac OS X: Kernel Environment 

• Inside Cocoa: Object-Oriented Programming and the 
Objecrive-C Language 


Upcoming Seminars 
and Events 

For more information on Apple developer events please 
visit the developer Events page at: 
http: //developer, apple, com/events/ 

Training and Seminars 

Programming with Cocoa 

Taught by Aaron Hillegass at the Big Nerd Ranch, Ashville, NC 
and Atlanta, GA. Five-day classes are taught on developing 
web-based and Mae OS X applications. 
http: !/www. bignerdranefx com/when . hunt 

Developer Related Conferences 

Game Developer Conference, San Jose , CA 
March 20-24 

For 15 years, the Game Developers Conference (GDC) has 
been the independent and unbiased forum where game 
development professionals from around the world gather to 
share ideas anti build the skills essential to creating the next 
generation of interactive entertainment. Apple will be exhibit¬ 
ing at this year’s conference. 

Worldwide Developers Conference (WWDC) 2001, 

San Jose ( CA 
May 21-25 

Register now for Apple’s Worldwide Developers Conference 
2001, which takes place in San Jose, California from May 21- 
25. ADC Premier members receive a free pass to the confer¬ 
ence, ADC Select members receive discounts for early registra¬ 
tion, and ADC Student members can apply for a scholarship to 
attend for free! For schedules and other details check out: 
http://www.applexom/developer!wwdc200J/ 

If you missed last year’s conference, a great way to get 
ready for WWDC 2001 is to purchase our five volume WWDC 
2000 Conference Sessions on DVD-ROM, This set contains 
over 80 hours of detailed technical information from WWDC 
2000 and is deeply discounted for ADC Members. Additional 
information on this product can be found at: 
http: //developer, apple, com/products/ 

MacHack Conference, Dearborn, MI 
June 21-23 

MacHack, in its sixteenth year, remains centered around cut¬ 
ting edge software development MacHack's uniqueness 
derives from the informal feel and the LIVE coding that 
occurs around-the-clock during the conference. 
http://wwu\ machack.com/ 
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Carbon: An Essential Element of Mac OS X 

Continued from page 59 

An Investment in the Future 

Carbon is more than just a porting tool. It’s a hill-featured API that 
provides a solid foundation for serious ongoing development. Apple 
is working hard to make sure Carbon has everything you need to 
write world-class applications, now and in the future. 

Mac OS X, with its killer graphics and superior performance, 
presents an opportunity for you to revitalize or even reinvent your 
application. Your goal should be more than simply getting your code 
running on Carbon—it should be to create a compelling new 
product that takes advantage of everything Mac OS X has to offer 
When you’re finished, be sure to let Apple know about your 
product, so we can list it on the "Built for Mac OS X" web page 
located in the Mac Products Guide (MPG): 
http://submit, macsoftware, apple, com/usupdate/upindex. html 

Until Next Time 

With Mac OS X shipping on March 24 t the demand for native 
applications will be huge. Carbon is one way to bring your Mac OS X 
product to market quickly. Future articles will cover Cocoa, Java, and 
other options for Mac OS X development. 

Whatever path you choose, Apple’s Worldwide Developer 
Relations team is here to help. For technical support, visit 
http://devcloper.apple.com/products/techsupport/. Better yet, sign 
yourself up on the Carbon Development discussion list (carbon- 
development@lists.apple.com). This list is monitored by Apple 
technology managers, engineers, and your fellow developers from 
around the world. It’s a great place to gel answers or share your 
knowledge, and it’s free. To sign up, go to http://lists.apple.com and 
search for Carbon Development. See you there! 

Discounts on 
Mac OS X Migration 

Bring Your Apps to Mac OS X 

With Mae OS X Public Beta here, and the commercial release just 
over the horizon. Mac developers everywhere have a huge need for 
Carbon and Cocoa application porting, Aqua user interface 
implementation, and driver development services. Several high- 
quality software engineering firms, in association with the Apple 
Developer Connection, are offering these services at very attractive 
discounts to all ADC Select and Premier members. 

J bttp: //developer, apple, comfmktjmacosxm igration. html 

End-User Tech Support 

We all know how expensive and time consuming it is to set-up and 
maintain a comprehensive customer tech support department. To 
support developers in their migration to Mac OS X, 877Macfank has 
designed an exclusive and affordable tech support staffing program 
for ADC Premier and Select members. 
http://developer, apple, comimktfmactank html 


Did You Know? 

M uch of Apple's technical documentation is geared 
toward helping Carbon application developers. To 
see the scope of this documentation, check out the 
Carbon documentation suite on the Web at: 
http://developerapple.com/techpubs/macosx/Carbon/ 
carbon.html 

Here you will find the “Inside Carbon” suite of API 
documentation for the nearly 100 Carbon-compatible 
managers, organized by topic. This documentation includes 
Carbon inclusion status, per-funetbn release availability, 
and porting notes to help you modify your legacy Mac OS 
code for functions that aren't supported. Some documents 
also describe concepts and include sample code to help 
you revise your legacy Mac OS applications for Carbon and 
to create new Carbon applications. You’ll also find at the 
Carbon documentation site a number of relevant 
programming guides, such as "Aqua Human Interface 
Guidelines," “Carbon Porting Guide," and "Moon Travel 
Tutorial: Creating a Carbon Application." 

The Carbon documentation suite is also available 
on the Mac OS X Developer CD. When you install the 
Developer package, you can also access this 
documentation from the Developer Help Center using the 
Help Viewer application. 

If you have legacy Macintosh applications that you 
wish to port, be sure to use the Carbon Dater took Carbon 
Dater produces an HTML report customized for your 
application. The report lists function calls and code usage 
that you may need to change, and offers the latest 
documentation to help you make those changes. Although 
the Carbon documentation site provides a link to Carbon 
Dater, the tool itself is not included on the Developer CD, 


Carbon Tips & Tricks 

The Apple Developer Connection web site titled Carbon 
“Tips & Tricks’' is dedicated to sharing special techniques 
for debugging and building Carbon applications. 

Visit us at: 

http://developerappie.com/macosx/carbon/ 

tipsandthcks.html 










MULTIMEDIA 


By Ro n Deans 


Putting An MP3 Player In The Dashboard 


Adding Code To Play MP3 Files Into The 
PoiverPlant Dashboard Example 

IivmomjcnoN 

To me, one of the coolest things in programming is when 
something that someone else wrote works easily. You make one call 
and something you know took a lot of doing just happens, as 
advertised. Unfortunately this is a rare thing in the world of the 
programmer, but in this article you'll see one of those things happen, 
thanks to die QuickTime team. Well see how to write an application 
that plays MP3 hies, with an absurdly small amount of code. 

One caveat before we start. There is more than one way to play 
an MP3 file from code on die Mac; diis Ls just one. I recently read a 
comment in an article in Lhe Game Developer Magazine that is relevant 
here, "Fast, cheap, gtxxJ — pick two." This article will show you how 
to do it hist and cheap. My personal opinion Ls that in most cases it s 
stilt pretty good, but there Ls a problem with QuickTime playback on 
cooperative operating systems that causes skipping in some cases. The 
implementation this article uses will skip, especially when it Ls in the 
background and you are doing other diings in die front. The good 
news is that it wont skip under Mac OS X. and well be writing a 
Carbon application. 

Starting wtih the PowtrPl\nt Dashboard 

Were going to use Metrowerk’s application framework 
PowerPoint to implement this application. Why PowerPlant? 
Because 1 like it and it gives us a starting place. The starting 
place is the Appearance Stationary 1 . Create a new Project Click 
the “Mac OS PowerPlant Stationary 1 ’ wizard. Tell Code Warrior 
where you want to save. When the Stationary window comes up, 
expand Carbon, and select Appearance. CW will then create a 
folder on your drive with the Dashboard application in it. 
Dashboard is a simple application with one window, It is this 
window we are going to turn into our MP3 player’s controller. 

Let s start out in Constructor and make our controls. Open the 
AppResource.s. ppob file. Double click "Appearance Window". 
Delete all of the objects in die window. Now r add 3 
LCmdBevelBuaons, "Play”, "Stop”, “Pause”. We’re going to use 


LCmdBevdButtons so we don’t have to add listening code to out¬ 
class. instead, w r e can just hook into the Command handling 
mechanism already in place. When configuring each button, you 
need to change diree fields: the Pane ID, Title, and Command 
Number, When you get back to die project, you will need to add 
constants for these commands. Table 1 shows die values I used. 


Tide 

Const 

Bine ID 

Command Number 

Play 

cmd Play 

‘play’ 

1000 

Stop 

cmd$top 

‘stop* 

1010 

Pause 

cmd Pause 

J paus 

1020 


Table I. Constant and command lvalues. 



Figure 1. Controller Window in Constructor. 

Tin Constructor, die controller window looks like Figure 1, Since 
we used LCmdBevelBuaons, we have to add menu items with the 
command numlx j is. Add a new menu in Constructor. Call the menu 
“Controls." Give it three commands with tides and c<>mmand numbers 
just like die buttons. Don’t forget to add the menu to the Menu Bar (or 
it won't show up in your application). 

At this point, you can run the application and a window will show 
up w ith all of the buttons disabled. 

Wrtitng the Code 

Now we need to write some code to make our player work. 
Everything Ls going to happen in die CAppearanceApp class. Well 
handle opening the MP3 file and the Play. Stop and Pause controls from 
here, in order to do this, we are going to have to add a few routines 
and instance variables. Open the header for GAppearanceApp. We 
need to add a variable that holds die FSSpec of the currently playing 


Ron Davis is a consulting Engineer in Apple's iSemces group, He s also the author of his own more complete MP3 player, MP3 Hit List, which 
is soon to be released. 
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1 Scripting Saves Time - InsrallerMaker 
K/ provides hill scripmhiliry for all features. 
Automating the build process saves time 
and helps ensure the integrity of your installer. 


Trialware in Minutes - Creating trial ware is a 
breeze with InsrallerMaker. With just a few ^ 
clicks, and no extra coding, you can create M 
trialware that is e-eommerce ready. 


Update in a Flash - Easily build intelligent 
M diff" files in installers to create small updaters for quick 
online distribution. From one simple installer, you can 
update 68k, PowerPC or FAT applications. 


More Details Online - There’s a lot more 
InstallerMaker can do for you. Get all the 
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When Time Is Money, Get It Done Fast! 

Build Smaller Installers - With Stufflt InstallerMaker, you’ll build installers 
faster than ever before! Compress your installers an average of 15% smaller 
using the power of the Srufflr Engine -. Smaller installers download faster, 
provide added space on CDs and servers, and increase network bandwidth. 


• Resource 
Installation 


Quickly Create Demoware - Easily turn your application into a polished 
demo, just set the number of days for the demo to be active, paste in the 
graphics, and you're done! 


• Built-In 
Resource 
Compression 


Archive Freshening - Automatically update your installer project file; 
eliminate repeated searches for modified files. 
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void 


RegisterGlasses(); 


MP3 file and a QuickTime Movie variable of the currently playing MP3 
The standard appearance application doesn't keep track of the 
window once it creates it, but we need to make sure there is only one 
window open, since we can only play one MP3 at a time. For tins 
reason, we need to add an instance variable to hold the window. Tins 
"one MP3 at a time" limitation is ours, not QuickTime's. You could play 
multiple sound files at once if you wanted. 

QuickTime treats an MP3 just like a movie. As a matter of fact, 
you could use a movie controller to play the MP3 and you wouldn't 
need our command buttons. On the other hand, you would lose some 
level of control and you would liavc to display something on tire 
screen. Our method will allow us to play an MP3 with only die UI we 
want, or no UI at all. 

There are Lw r o other things that need to be added to the class 
declaration of CAppearanceApp. Well he writing two new methods, 
ChooseFile and SetUpMP3. Listing 1 shows the complete 
CAppearanceApp class. 


listing 1: Declaring our custom class 


CAppearanceApp, li 


class CAppearanceApp : public ^Application [ 


publics 

virtual 


CAppearanceApp(}; 
-CAppearanceApp0; 


virtual Boolean ObeyCommand( 

CoirartandT inCcnnnand * 

void* ioParam “ nil): 


virtual void 


virtual void 
void 

protected: 
virtual void 


FindCommandStatus( 

Comma ndT inCommand, 

Boolean^ outEnahled, 

Boolean^ out UsesMark. 

tfltrti6& outMark, 

Str255 outName ); 

ChooseFile(); 

SettJpMP3( bool startFlaying ): 
StartUp(); 


LWindow' * 1 mWindow; 

FSSpec mMPSFile: 

Movie mMovie; 


J; 


Now let's move into the actual code of the class. We will be 
starting with the constructor. We need to do a couple of tilings in here 
to seL up QuickTime. Listing 2 contains the altered constructor. 

listing 2: The updated constructor for CAppearanceApp 

(lAppi'urttnccApp.L’p 


CAppearanceApp::CAppearanceApp() 

:mWindow[NULL]* mMovie(NULL) 

t 

boat cantRun s false: 

// Raster ourselves with the Appearance Manager 
if (UEnvironment::HasFeature(env_HasAppearance)) f 
::RegisterAppearanceClientQ; 

} 

long results 

if {::Gestalt[gestaltQuickTime, iresuit) 1 = noErr ) f 
// pin. a dialog lien: dial says we need QT 
cantRun - true; 

I else 
( 

::Gestalt(gestaltOuickTimeVersion. &result); 
if ( result < 0x0400 ) 

f 

cantRun “ true; 

\ 

I 

if C cantRun ) 

[ 

//you slnKild put up an alert here telling the user why. 

ExJ tToShel 10: 

I 

RegisterClasses0; 

EnterMovies(): 

1 
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The first thing we do is initialize our mWindcw and mMovie 
variables to NULL, We are going to check them later to determine if 
die window or movie has already been created, so they had better be 
NULL the first time we check it. 

We need to check for QuickTime, We do tins with the Gestalt calls 
in the center I went ahead and checked for QuickTime version as 
well If we don’t have QuickTime, we exit the program right here. If 
we do have it, we register our classes and call EnterMovies. 
EnterMovies is the QuickTime initialization call and must be made 
before calling any other QuickTime Routines. 

Listing 3 contains the new CAppearanceApp::Startup routine. The 
default behavior of Appearance is to open a new window at start up. 
But what does New mean in our app? Tills isn’t a recording app; there 
are no new MF3s to be created. So what we arc going to do is stop 
New from happening at all. Wliile we’re at it t well make Open happen 
in its place, which will let us open an MP3 file and play it. 

Listing 3= The start-up routine 

CAppearanceApp: Startup 

void CApp e aranceApp::Sta rtUp() 

\ 

ObeyCommand(cmd_Op en, nil); 

] 

Now we need to make sure the New menu command isn’t 
even available to the user and that the commands for our controls 
are enabled. Go to FindCommandStatus and change the cmd_new 
to cmd_open. Then add eases for the constants we defined for our 
commands. When it is done, your FindCommandStatus should 
look like Listing 4. 



1-88-USB USB US 

-or- (1-888-728-7287) 

worldwide Distributors of USB 
and FireWire Parts, 
Peripherals and Accessories 

Hey Developers: 

http: //www. usbstu 11 . com/deve 1 oper s. html 

1-877-4 HOTWIRe 

-or- 1-877-446-8947 

fCreWCreStuff 


Listing 4: Adjusting our menu items 


<] AppcarancrA pp:: Fin lK >m rrwndStj ti i> 

void CAppearanceApp::FindCommandStatus( 

CommandT inCommand, 

Boolean!* outEnabied, 

Boolean^ outUsesMark, 

UIntl&i outMark, 

Str255 outName) 

t 

switch (inCommand) [ 
case cmd_Open; 
case tmd_Play: 
case cmdjjtop; 
case cmd_Pause; 

I 

outEnabled = true; 
break: 

J 

default: t 

LApplieatIon;:FindCommandStatus(inCommand. outEnabled, 
outUsesMark. outMark* outName); 

break: 

1 

) 

1 

To handle the Open menu command, we need to change a 
couple of things. As all Power Plant programmers know, you do the 
actual work of a menu command in the ObeyCommand method and 
that is where the code Is right now to display the window. Were going 
to change tliai a little. We need to pick a file before we open the 
window, so weTe going to create a new method called GhooseFile to 
handle picking the file and opening the window, listing 3 contains the 
complete GhooseFile method 

Listing 5: Choosing a file 


CAppearanceApp:: ChooseHle 

void CApp g a ran c eApp::Choo seFile () 

I 

PP_StandardDiaiags: :LFileChooser chooser: 

NavDialogOptious* options = chooser.GetDialogOptions(); 
if (options 1= nil) I 

options -)diaiogQptiojiFiags “ kNavDefaaltNavDlogOptions 
+ kNavNoTypePopup 
+ kNavAllowMultipleFilcs; 

3 

chooser.SetObjectFilterProc( NavServFileFilterProc ); 
if (chooser.AskOpenFile( LFileTypeList(fileTypes_All))) f 
// Id tile filter pmc handle types 
chooser.GetFiieSpec( 1, mMPSFile): 
if ( mWindow = NULL ) 

I 

iriWindow = L Window:; CreateWindow (PPob_SampleWindow, this); 
ThrowIfNil_(mWindow): 
mWindow-)Show(); 

1 

SetUpMP3( true ): 

I 

I 

A number of things are happening in this routine, We are using 
PowerPhnfs UileChooser to handle the open dialog, Under Carbon, 
this will always use Navigation Services, Fust we set up Navigation 
Services options, telling it not to use the types pop-up menu and to 
only pick one file, (Yes, adding kNavAifowMultipleFiles only lets you 
pick one file. Go figure.) Then we tell the LFileChooser and Nav 
Services to use our filter procedure. Well talk about the filter proc in a 
minute, .After the set up, we do die AskOpenFile, which will h an dled 
by putting the dialog up and getting its results. If the user doesn't 
cancel, it will return true and we will execute the code inside our if. 
The first thing we do is get die file system specification of the file 
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Lhe user picked. We assign it to our instance variable for later use. Then 
we create Lhe window if it doesn’t exist. Once the window exists, we 
call SelUpMP3. which we are going to write next. 

Before we go on, Listing 6 shows the Nav Services Filter proc Fm 
using. It checks to see if the type of the file is one of the two MP3 file 
types I know r about and it also checks to see if the file ends with .mp3 
or .MP3, which should catch most MP3 files. 

Listing 6: Filter files for the Open dialog box 


NavServBIcFdterP'roc 

pascal Boolean NavServFileFilterProt ( 

AEDesc* theltetnAEDesc, void* info. 

NavGallBackUserData /* callBackUD */ H 
NavFilterModea /‘filterMode*/ ) 

I 

OSErr theErr = noErr; 

Boolean display “ false: 

NavFileOrFolderInfo* theInfo = (NavFileOrFolderInfo*}info: 
if ( theItemAEDesc‘>descriptocType = typeFSS ) 

{ . 

if ( thelnfo-HsFolrfer ) // show folders and volumes 

{ 

return truer 

) 

1 

StAEDescrlptor aSpecDesc; 

if :AECoerceDeac(theItanAEDefic, typeFSS, aSpecDesc) “ noErr) ! 
FSSpec spec: 

OSErr err = ::AEGetDescData(aSpecDesc* &spec, 
flizeof(FSSpec)); 

ThrowIfOSErr_(err): 



Mac OS X 


Making the Move 


With IffrJFj £& ,Y just over the !ilj]jJMlT,l . 

Mac ie¥clQpCr$ everywhere have a 
major need for C AB B ON and 


FInfo finderlnfo; 

:iFSpGetFInfof &apec t Scfinderlnfo ); 

LStr255 tempString( spec,name ): 
if tempString.EndsWith( H, \p.mp3" ) |l 

tempString,Endstfith( M \p,HP3* ) } 


display m true: 

I 

if ( finderlnfo.fdType = ‘MFG3 f || 

finderlnfo.fdType = *MF3 * ) 


display = true: 


1 

return display; 


application porting. user interface 

implementation, and OFIRIR development 
services. Toward that end, several 
high-quality engineering 

firms, in association with the HPPLI 
DEVELOPER CONNECTION, are offering these 


Loading and Raying the MP3 

Now r we J re ready to load the file and play it. The loading of the 
file takes place in the method SetUpMP3, listing 6 contains the 
complete routine. Playing an MP3 using QuickTime is just like playing 
a movie. The only difference is w r e don’t have to worry 7 much about 
where it drawls. 


services at very attractive discounts 
to all MX, Select and Premier members. 


void CAppearanceApp::SetUpMF3( bool startPlaying ) 

I 

// mMP3FUt lias been set with the file we want to play. 

// set it up to piny. 

if ( mMovie 1 = NULL ) 

1 

DifiposeMovle CnMoyie): 
mMovie = NULL; 

) 

mWindow->SetDescriptor(mMPBFile,name}; 

// get the movie from the file 
OSErr err: 

SI tit 16 movieRefNiim: 

err = : :QpenMovieFile(6iiiMP3File, tmovieRefNuiii. fsRdPerm): 
ThrowIfOSErr_(err): 

SIntl6 actualResID =■ BoTheRightThing; 

Boolean wasChanged; 

err = : iNewMovieFromFilef&mMovie. ffiovieRefNum, &actualReslD t 
ni 1, newMovieAc five. kwasChan ge d); 
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development. Our team of senior engineers averages over 
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Eat your vegetables. 

□ Exercise every day. 
0 Port to Mac OS X. 

□ Call your mom. 


! All of these are good for you. 
We can make one of them easy. 


Since 1989, The Omni Group has worked with the technologies that have been refined into Mac OS X. 

Moving to Mac OS X is a big step for your company, and you need consultants who can help you both 
plan how best to make the transition and follow whatever path you choose. 

That's been our business for years. No matter what kind of product you have, we can get it up under 
OS X, fast: 

• Real games: We ported id's Doom and Quake games to NEXTSTEP and OS X. Quake 2 took us a week. 

• Big apps: We ported Adobe's frame Maker to NEXTSTEP and Sun's Concurrence to OpenS tep/Soiar is. 

• Big libraries: We ported the Oracle 8 client libraries which Apple ships today in OS X Server. 

• Serious drivers: We ported 3dfx's Glide and wrote Voodoo2 and Rendition drivers for OS X Server. 

We've written new mouse drivers for OS X Server and joystick drivers for OpenStep. 

• New apps: We wrote OmniWeb, the only native OS X web browser, and OmniPDF, the native Acrobat 

viewer for OS X. 

Mac OS X is what we do. Let us help you do it, too. 


The Omni Group 



2707 Northeast Blakeley Street 
Seattle, Washington 98105-3118 
www.omnigroup.com/consultlng 


sales@omnigroup.com 
800.315.0MNJ x201 
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ThrowIfOSErrJerr): 

err = : :CloseMovieFile(movieRefNtm): 

Th rowlfOSEr r_ (err): 

// start tlie file playing 
Rect movieBox: 

:;GetWovieBox (mMovie, kmovieEox): 

:;Qf£setRect (kmovieRox. movieEox,left, -mavieBox.top); 

:: SetMovieBox (mMovie. tamieBox): 

:iSetMovieGWorld {mMovie, mWindov->GetMacPort(), nil); 

;:FrerollMov±e( mMovie. 0. ;;GetMoviePreferredRfltetmMovie] 

// tried asking for less than the whole movie but it seems to load it all anyway, 
err = : :LoadMovieIntoRani( mMovie, Q ( 

: tGetMovieDuration(inMovie) . unkeepInRam) ; 

If ( startPlaying ) 

\ 

ObeyCommand( cmd_Play ); 

] 

I 

Listing 6: SetUpMP3 t the routine that loads our MP3, 

Our program Ls only going to play tine MP3 at a time, and we will 
reference that MP3 internally as a QuickTime Movie type. Our 
reference variable is mMovie, which we initialized to NULL in the 
const uctor. The first tiling we do in our routine is check to see if there 
is already an existing mMovie, If so, we need to dispose of it properly 
via QuickTime's DisposeMovte routine. 

Now we have a dean slate and the first thing we do is set the title 
of our window to the name of the hie we are going to play. Then we 
load the movie. We tell QuickTime to OpenMovteHle. II there is a 
problem opening the file, like it isn’t really an MP3, then we throw and 
get out of the routine. 

Next we tell QuickTime to create a new Movie for the file, 
NewMovieFroniFikc Tills routine takes our mMovie variable, the 
inovieRdNum we got from our open coll the attualResID, flags that 
tell it we want the movie active, and a Hag telling us if they had to 
d range any references we gave them Notice we set actual Led D Lo the 
name of a Spike Lee movie. Tills variable is the resource ID of the first 
resource in our movie file. We set it Hi DoTTieRightThing, in a vain 
attempt to get Spike's movie, hut we won’t and QuickTime will .set our 
variable to the actual resource ID, or in our MP3 case, nothing. 

Now we have got the movie in QuickTime and we can do.se die 
file. Before we tun play the file we need to set up its "Movie Box," 
which is where we want it to play. We do this by getting the current 
box. making it nothing and assigning the G World to our window. 
None of this really matters to us, but it does to QuickTime. 

We do a couple of things to try and minimize skipping. First we 
preroll the movie. This causes the loginning of the movie to be 
buffered, LI you were opening a stream, you’d have to call 
PrePreRollMovie, Then we try and load all of die movie into RAM, If 
this succeeds well eliminate skipping. The last parameter of the call is 
set to unkeeplnlium, which Ls a constant that will allow die memory 
to lx.* purged if it is needed. You can set it to keepInRam, which won’t 
allow the memory to lx: freed I did this and it sucked up a huge 
amount of RAM and brought my MP3 player to a screeching halt. 
Remember most MIHs are rather big. IVe got the Rush 2112 track I 
ripped, which Is 21 minutes long and 19 Meg on disk. So loading Isn't 
always practical Of course, given OS Xk different memory model, 
loading probably works well 

Before we leave the routine, we check its parameter and if it is 
true we give the command to play, w hich will start the file playing. 

The last routine we need to write is the ObeyCommand method. 


Tills Is a standard PowerPoint method that handles menu commands 
and will handle our buttons. It Is in Listing 7. 

Boolean CAppearanceApp::ObeyCommand( 

ComnandT inComnand, 
void* ioFaram) 

1 

Boolean cmdHandled — true; fl Assume we'll handle the 
command 

switch (inCommand) I 
case cmd_Open; 

I 

ChooseFileC); 

] 

break; 

case cmd_Flay: 
t 

::StartMovie( mMovie ); 

I 

break; 

case fund_Stop; 

( 

;;StopMovie( mMovie }; 

;:SetMovieTimeValueC mMovie. 0 ): 

1 

break; 

case cmdLPause: 

| 

;:StopMovie( mMovie ): 

1 

break: 
default: 1 

cmdHandled = LApplication::ObeyCommand(inCommand, 
ioFaram); 

break: 

I 

I 

return cmdHandled; 

1 

Listing 7: Obeying commands for the player, 

The first command we handle Ls the open command, which just 
calk our ChooseFilcf) method Next we handle the Play command. To 
start our already loaded movie playing, we just call QuickTime’s 
StartMovie with our mMovie as die parameter. To Pause the movie, we 
call StopMovie. StopMovie doesn’t move where the “playhead” Ls for 
the movie, so if you call StartMovie again it will start playing were it 
w r as. The proper behavior for a stop button is to go back to the 
beginning of the song. So to handle die Slop command, we stop die 
movie and rhen move the play position back to the beginning, using 
SetMovieTimeValue, You could use SetMnvieTlmcValue to set die play 
head whereever you wanted in die song. You could even hook it up 
to a slider and let the user do it. Ill leave that as Lin exercise for die 
readers, 

Conclusion 

Tliat is the basics of playing an MP3 file using QuickTime. If you 
want to learn more you need to check out the QuickTime AIT web 
site, and maybe subscribe to die QuickTime .API mailing list. 

Biblography 

■ QuickTime API 

<http://developeTappl0.com/techpu bs/quickti me/qtdevdocs/ 
RM/fra meset htm> 

* QuickTime API Mailing List; 

<http://l ists, a ppl e.com/mai I ma n/listi nfo/qu ickti m e-api> 

* 2112. Rush 

* Do The Right Tiling . Director, Spike Lee. ESQ 
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Smalltalk 

1 recently ran across a paper which describes a study 
comparing the productivity and efficiency of several 
programming languages. While it's difficult to draw 
concrete conclusions from such a comparison, the paper 
did make an interesting observation: programmers of 
scripting languages (such as Perl, Python, and Tel) tend to 
use language features differently than programmers of 
non-sertpting languages (such as C, C++, and Java), 
Specifically, they noted that the former group used data 
structures (such as arrays and dictionaries) which are built 
into the language, where as the latter group consistently 
implemented their own data structures from scratch rather 
than using those provided by their languages' standard 
libraries* This reminded me of an observation that I had 
made of my own programming practices — namely, that 
learning a new programming language influences how 1 
program in other languages. For example, after learning 
Perl 1 tended to use associative arrays (also known as 
hashes, dictionaries or maps) more frequently in other 
languages, and implemented custom objects and data 
structures less often* In fact, this makes a lot of sense 
when you start to think about it — different languages 
have different design goals and cultures, and lead you to 
thinking about programming from different perspectives* 
As a developer, I view a programming language as a tool 
— albeit a rather important one* Like most other tools, 
people tend to have a favorite, but you are always better 
off having a variety to call upon to tackle different 
problems. And with programming languages in particular, 
I would argue that knowing a variety of languages can 
make you a better programmer in your language of choice. 

So in the spirit of broadening our horizons, this month 
we are going to talk about the programming language 
Smalltalk* The goal here isn’t to convince you to use 
Smalltalk for your next project, but rather to encourage you 
to read up on, and play with, a new language, as an 
incubator for new ideas and because, frankly, it’s fun. 

An empirical comparison of C, C++, Java, Perl, Python, Rexx, and Td 

<http://wwwjpd.ira.uka.de/~prechelFBibtio/jccpprt_comptiter20Q0.pdf> 

What Makes Smalltalk Special 

Smalltalk has been around for quite a while, and in 
fact its genesis dates back to xAlan Kay’s Dynabook project 
at Xerox PARC, the same project which lead to the 
development of the graphical user interface (GUI). It was 
one of the things shown to Steve jobs on his famous trip 


to the research center, and according to the story Xerox 
was more worried about letting Smalltalk out of the bag 
than they were about revealing the GUT* 

Smalltalk was arguably the first pure object-oriented 
language; everything in Smalltalk is an object — there are 
no primitive types* It w r ill look a bit familiar to Objective-C 
programmers — the message-passing syntax (as w^ell as the 
object model) of Objective-C was based on Smalltalk, the 
most obvious difference being that Smalltalk does not 
enclose its message sends in brackets* (So, the Objective-G 
statement “[dog fetch :stick]” would be just “dog fetchrstick" in 
Smalltalk.) Smalltalk was a language ahead of its time in 
many ways* For instance, inherent to all Smalltalk 
development systems is a class browser. You’ve probably 
seen class browsers before, either in connection with Java, 
or in Apple’s Project Builder, or in some other IDE. What 
sets the Smalltalk Browser apart is that all development is 
done there — Smalltalk source code does not live in 
separate text files* The plus side of this is that the 
programmer doesn’t have to worry about how source code 
should be organized, or about what classes and methods 
live in what files — this is taken care of by the development 
environment, freeing the programmer of all of the mundane 
details. This approach also simplifies the language: for 
instance, there is no syntax for declaring a new class, 
because none is needed — you simply use the "new class" 
command in the browser GUI. (On the other hand, one of 
the down sides of this is that it is awkward to print out 
Smalltalk code, or to include it in email messages.) 

Another seemingly strange detail you wall notice is 
that there is no “main" entry point to a Smalltalk program, 
or even clear distinctions between programs. To run some 
code, you simply select it in the Browser and choose “do 
it” from the menu. This melding of the development 
environment into an integral part of the language may feel 
uncomfortable to programmers who are used to a strict 
separation between the two, but if you give it a chance 
you may find it refreshing. Although Smalltalk is not new, 
somehow- this approach feels like progress over the 
predominant “programs == text” paradigm, 

A must-read for anyone interested in Smalltalk is 
Design Principles Behind Smalltalk, a high-level overview 
of the philosophy behind the language, originally printed 
in the August 1981 edition of Byte Magazine , which 
marked the first public appearance of Smalltalk. A brief, 
no-nonsense description can also be found in the TUNES 
Project's Review of Existing Languages. Also, you’ll want 
to refer to either the Google Web Directory or the Open 
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Directory pages on Smalltalk for links to numerous other 
resources, and to both of the major FAQs for answers to 
many common questions. Finally, the online version of 
AOKl AtsushPs book Smalltalk Idioms is a fair-sized 
tutorial which has a nice introductory section to set the 
conceptual stage. 

Design Principles Behind Smalltalk 

<http://usersjpa,net/~dwighth/smalltalk/byte_aug81/design_principies_behind_ 
Smalltalk, html> 

Review of existing Languages 

<http://www2 .tunes. org/Revi ew/Languages, html#S mal Ita lk> 

Google Web Directory - Smalltalk 

<http^/diredory,googlexom/TopyCornpiJters/Programming/Langu^es/5mal!talk/> 

Open Directory: Smalltalk 

< http://dm oz. o rg/Com puters/Prog ra m m ing/Lan guages/S ma llta I k/> 

Dave's Smalltalk FAQ 
<http://www.dnsmith.com/SmallFAQ/> 

Smalltalk FAQ (v.1.0) 

<http://www.faqs.org/faqs/smalltalk-faq/index.html> 

Smalltalk Idioms 

<http://www. s ra xo. j p/pe op le/a o ki/Sma 11 ta I ki d i oms/ i nd ex_e. htm> 

The Smalltalk Language and Object-Oriented Design 

As 1 said at the beginning of this article, 3 see 
Smalltalk in part as a jumping off point to learn about 
object-oriented programming in general, to be applied to 
programming in other languages as well. And Smalltalk is 
the perfect playground for this. It is a pure object-oriented 
language — there are no primitive types, and almost 
everything is handled through messages sent to objects. 
This in itself simplifies the learning of the language, as 
there is a consistent semantics to all variables, a feature 
lacked by hybrid languages such as Java, C++, C# ( and 
even Objective-C T (Take a look at the interesting article 
Primitive Types Considered Harmful on IBM's web site for 
a discussion of this, in the context of Java. ) Continuing 
the same theme, Smalltalk is completely dynamically 
typed — variables do not have type declarations, so that 
all type-related information is contained in the objects 
themselves, and is accessed at run time rather than at 
compile time. Also, there are only five reserved words 
(self, super, nil, true, and false), and minimal syntax. In 
fact, there are actually no flow-control structures in the 
language (such as “if”, “for' 5 , or “while”) — flow control is 
also handled via messages to objects. This will seem 
strange to programmers of other languages, as almost 
every language contains the same basic branching and 
looping constaicts (think of C T Java, Perl, and Python). 
Overall, the clean design of the language promotes a 
focus on the design of the programs you write with it, as 
there is minimal syntax to get in the way of learning and 
using the language. Although Smalltalk was originally 
designed to be usable by children, its simplicity makes it 
deep and abstract as well. 


Primitive Types Considered Harmful 

<http://www7software Jbm.com /vad. n sf/Data/Do cu me nt2 712 > 

So how does Smalltalk handle situations that call for an 
"if" or a loop? The language has a construct called a block — 
some other languages, such as Perl, have similar constructs, 
but they are not typically used in the same manner that 
blocks are used in Smalltalk. A block is just, well, a block of 
code (enclosed in square brackets), and it can be passed as 
a parameter to a method just like other objects. Conceptually, 
passing a block to a method is like passing a function pointer 
in other languages, except that rather than defining a 
function in one place and then passing the function pointer, 
you just put the code right where you are going to use it. In 
practice, blocks are used extensively in Smalltalk (more 
extensively than function pointers are used in other 
languages). Using this construct, a loop is implemented by 
sending to a collection a message (usually “do;") with a block 
as a parameter — in effect, the message asks the collection 
(such as a list) to execute the block for each object the 
collection contains (passing each object to the block as an 
argument). Similarly, conditionals are implemented by 
sending the "ifTrue;” message to an expression which 
evaluates to a boolean, again passing a block as a parameter 
—- so the "true” object knows that it should evaluate the 
block, and the 'false 11 object knows that it shouldn't. The 
syntax (as well as the idea) takes a bit of getting used to, buL 
in addition to simplifying the semantics of the language, this 
approach makes it natural for die programmer to define his 
own looping and conditional constructs, giving the language 
a great flexibility while maintaining Its clarity. Take a look at 
the Smalltalk Industry Council's An Intro to Smalltalk for an 
example illustrating this syntax, as well as a brief sketch of 
Smalltalk's history, and UIUC’s Visual Works; Smalltalk basics 
page for a pithy overview of the most important and 
interesting features of the language. 

Smalltalk Industry Council - An Intro to Smalltalk 

<http://vvww.sticorg/news.ez?viewUnk=7> 

Visual Works: Smalltalk basics 
<http://wiki.cs.uiuc.eduA/isualWorks/SmaIltalk-hbasics>- 

Once you've become familiar with the basics of 
Smalltalk, you can move on to some of the discussioas of 
object-oriented programming which fit naturally with the 
language. Topics include the concept of "super and whether 
accessor methods are a good idea. On the web, three good 
places to start are articles on the Bytesmiths, Instantiations, 
and I.TTUC sites. You 11 also find many interesting articles in 
the book Kent Beck's Guide to Better Smalltalk; A Sorted 
Collection (ISBN: 0521644372). 

Bytesmiths' Smalltalk Publications 
<http://www.bytesmiths.com/pubs/> 
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Smalltalk Products - Publications 

< http:// ww w J nsta n ti ati o ns.co m/sts/pubs.htm > 

VisualWorks: Conversation topics 

<http://wi ki.cs. uiuc.edu/Visua lWorks/Conversation+topics> 

Squeak 

Because Smalltalk blurs the lines between 1DE T source 
code, and runtime, a Smalltalk development environment is 
almost like an operating system unto itself — in fact, early 
Smalltalk implementations ran on the bare hardware, without 
an operating system in between. Today, there are several 
Smalltalk implementations available (some commercial and 
some free), and each varies from the others in the details of 
the IDE and even the language itself. One of the more 
interesting environments is Squeak, a free, open-source, 
cross-platform, evolving Smalltalk. It is the perfect 
environment to play with as you begin to experiment (which 
does not imply that it is a “toy” implementation). Squeak 
actually originated at Apple, with a group of developers who 
wanted a non-commercial Smalltalk to use in a project they 
were working on — a group which in fact included Alan 
Kay, the driving force behind the original Smalltalk, Its 
development continued after some of the team moved to 
Disney, and Squeak is now open-source, with an active 
community behind it: there is even a newly published book, 
Squeak Object-Oriented Design it nth M u hi media 
Applications (ISBN: 0130280283), 

The Squeak Homepage 
<http://squeak.org/> 

Squeak for Mac OS X 

<http://www.metaobject.com/downbads/Squeak/> 

Part of its success undoubtedly stems from ils unique 
openness — it is in fact open and accessible on a number 
of levels. First, as mentioned above, it's open-source. 
Secondly, it is cross platform and highly portable —- one 
if the features of Smalltalk (and Squeak in particular) is 
dial it defines its own notion of a GUI, Consequently, the 
development environment itself, as well as the programs 
written in it, share a unified notion of a GUI, and Squeak 
looks pixd-ior-pixel identical on all platforms. (In case it 
isn't clear, lire entirety of the Squeak environment is itself 
implemented in Squeak Smalltalk.) The upside to this is 
that porting the environment is simplified, and Squeak 
now runs on a wide range of platforms, including the 
Macintosh (where it was developed), Windows, various 
Unix platforms, and even a few PDAs. The downside is 
that Squeak can look, w r ell, somewhat ugly and 
unsophisticated, and menus and windows in Squeak don't 
behave exactly the way a Macintosh user would expect. 
The next degree of openness of Squeak stems from its 
implementation: the Squeak interpreter is itself written in 
Smalltalk. As the story goes, the developers of Squeak, 
naturally, wanted to do all of their development in 


Smalltalk, but writing an interpreter on top of an 
interpreter would be unacceptably slow. So, they wrote 
their Smalltalk interpreter in a subset of Smalltalk, and 
they wrote a Smalltalk-tG-C translator, also in Smalltalk. 
Running the translator against the source of their 
interpreter gave them, finally, an independent Smalltalk 
interpreter, written in C, but without requiring them to 
ever actually program in C. (Whew!) In the end, this 
“translation” gave dieir interpreter a 450-fold speed 
increase. You'll want to read the full story on how Squeak 
was bootstrapped, and on how its runtime achieves high 
performance, in Back to the Future: The Story of Squeak; 
it’s actually quite clever and interesting, and a testament 
to what can be achieved by sticking to a good idea. The 
importance of this is that a competent Squeak 
programmer is automatically qualified lo play around with 
the internals of the Squeak environment. Contrast this to 
most other languages: a Perl programmer needs to know 
C in order to modify the Perl interpreter, and users of 
compiled languages have even less access to the internals 
of their environment. The Squeak community as a whole 
is thus uniquely equipped to drive its own evolution. 

Back to the Future: The Story of Squeak 

<http://u5ers.ipa.net/~dwighth/squeak/oopsla_squeak.html> 

For an overview of Squeak and what makes it unique, 
start with the Squeak Swiki. (A "wiki* is a web site where 
readers can contribute by adding to, and editing, the actual 
content.; a tL swiki” is a wiki implemented in Squeak,). Of 
particular interest are die sections Place in the Universe and 
7 he / Us to n - < >f Stft t eak, as well as the FAQ. 

Squeak Swiki 

<h ttp://m in now. ccgatech. edu/squea k/1 > 

Place in the Universe 

<http://minnow.cc.gatech.edu/squeak/15B> 

The History of Squeak 
<http://minnow.cc.gatech.edu/squeak/389> 

Squeak FAQ 

<http://minnow.cc.gatech.edu/squeak/471 > 

There are several tutorials available as well, either 
specifically aimed at Squeak, or written using another 
Smalltalk implementation but still mostly relevant. You may 
want to try them all as you get up and running. 

Squeak Tutorial 

< h ttp://sq uea k. cs. ui uc-edu/eph oe n ix_tu tori a l/in tro. htm t> 

Making Smalltalk: Spreading the 00 Fun 
<http://www.linuxgazette.com/issue59/steffler.html> 

Basic Aspects of Squeak and the Smalitalk-80 Programming Language 
<http://kaka.cosc.canterbury.ac.nz/~wolfgang/cosc20S/smalltalk1.html> 

An 1BM-SMALLTALK centric Tutorial 

<http://kaka.cosLcanterbury.ac.nz/~wolfgang/cosc205/STtutorial/index,htm!> 
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‘Without a doubt, the Premiere Resource Editor 
for the Mac OS ... A wealth of time-saving tools.” 

- Mac User Magazine Eddy Awards 

"A distinct improvement over Apple's ResEdit " 

- MacTech Magazine 

'Every Mac OS developer should own a copy of Resorcerer. 

- Leonard Rosenthol, Aladdin Systems 

Without Resorcerer , our localization efforts would look like a 
Tower of Babel Don 't do product without itT 

- Greg Galanas , CEO and President , Metrowerks 


“Resorcerers data template system is amazing. ” 

- Bill Goodman t author of Smaller Installer and Compact Pro 

tl Resorcerer Rocks! Buy it, you will NOT regret it” 

- Joe Zobkiw y author of A Fragment of Your Imagination 

Resorcerer will pay for itself many times over in saved time and effort >J 

- MacUser review 

"The template that disassembles ' PICT's is awesome!” 

- Bill Steinberg, author of Pyro! and PBTools 

“Resorcerer proved indispensible in its own creation!” 

- Doug McKenna , author of Resorcerer 
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Version 2.0 


The Resource Editor for the Mac™ OS Wizard 


ORDERING INFO 


Requires System 7.0 or greater, 
1.5MB RAM, CD-ROM 

Standard price: $256 (decimal) 
Website price: $128 - $256 
(Educational, quantity, or 
other discounts available) 

Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 

Payment: Check, PC’s, or Visa/MC 
Taxes: Colorado customers only 

Extras (call, fax, or email us): 

COD, FedEx, UPS Blue/Red, 
International Shipping 

MATHEM*STHETICS, TNG. 

PO Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 
Fax: (303) 440-0504 
resorcer er@m athe m a es theti cs. com 


* Very fast, HFS browser for viewing file tree of all volumes 

* Extensibility for new Resorcerer Apprentices (CFM plug-ins) 

* New AppleScript Dictionary (*aete*) Apprentice Editor 

* Mac OS 8 Appearance Manager-savvy Control Editor 

* PowerPlant text traits and menu command support 

* Complete AIFF sound file disassembly template 

* Big-, little-, and even mixed-endian template parsing 

* Auto-backup during tile saves; folder attribute editing 

* Ships with PowerPC native, fat, and 68K versions 


* Fully supported; it’s easier, faster, and more productive than ResEdit 
■ Safer memory-based, not disk-file-based, design and operation 

* All hie information and common commands in one easy-to-use window 

* Compares resource files, and even edits your data forks as well 

* Visible, accumulating, editable scrap 

* Searches and opens/marks/selects resources by text content 

* Makes global resource ID or type changes easily and safely 

* Builds resource files from simple Rez-like scripts 

* Most editors DeRez directly to the clipboard 

* All graphic editors support screen-copying or partial screen-copying 

* Hot-linking Value Converter for editing 32 bits in a dozen formats 

* Its own 32-bit List Mgr can open and edit very large data structures 

* Templates can pro- and post-process any arbitrary data structure 

* Includes nearly 200 templates for common system resources 

* TMPLs for Installer, MacApp, QT, Balloons, AppleEvent, GX, etc. 

* Full integrated support for editing color dialogs and menus 

* Try out balloons, ‘ictb’s, lists and popups, even create C source code 

* Integrated single-window Hex/Code Editor, with patching, searching 

* Editors for cursors, versions, pictures, bundles, and lots more 

* Relied on by thousands of Macintosh developers around the world 


Tb order by credit card, or to get the latest news, bug fixes, updates, and apprentices, visit our website*.. 

www.mathemaesthetics.com 














For further references on Squeak, the Phaidros 
Software web site has collected together several pieces of 
documentation into an online book, and you can find links 
to further references in the Squeak section of the Open 
Directory or on the Learning to Squeak page. Also of 
interest will be the Squeak Smalltalk Quick Reference, 
which will come in handy as you begin to program. Finally, 
for an interesting application take a look at the Squeak Web 
Server, an http server implemented entirely within Squeak. 

Squeak Online Book Contents 

< h ttp://www. pha id ros. de/DI GITALI S/eng I isch /sq k/sq kOOOO 2, htm > 

Open Directory; Squeak 

<http://dmoz.arg/C 0 mputers/Programming/Languages/Smalltalk/Sque 3 k/> 
Learning to Squeak 

<http://minnow.cc.gatedi.edu/squeak/377> 

Squeak Smalltalk: A Quick Reference 
<http;//www,mucow.com/squeak-qref.html> 

Squeak Web Server 

< http://m a cos, t u w ten. ac, at/Sq u ea k/we bS e rve r. htm I > 

Tiie Model-View-Controller Pattern 

The U1 of Squeak leads us it) another recurring topic in 
Smalltalk — design patterns. Once again. Smalltalk's pure 
object orientation make it the natural forum for the 
discussion of design topics. One of the earliest design 
patterns, and possibly the most famous, is the Model-View- 
Controller (MVC) pattern, which originated as the paradigm 
for the user interface or Smalltalk programs. In brief, the MVC 
pattern is a strategy for separating the user interface of an 
application from its core logic, in part to promote code reuse 
and to insulate the different logical layers of an application 
from changes in other layers. In MVC, the Mtxld is an object 
which contains the "business logic", devoid of any concept 
of how it might be displayed. The View implements the 
display of information — the actual windows and buttons of 
the user interface. Finally, the Controller handles user input 
{such as keyboard presses and mouse clicks) and triggers 
state changes in the Model and the View; it is where much 
of the code which is specific to a single application will live, 
and hence it tends to be the least likely to he reused in other 
applications. There are numerous variations on MVC, 
tailoring it to better fit different situations. Apple's 
Application Architecture documentation discusses h in 
connection with application design within the Cocoa 
frameworks, Java's Swing Ira me works are also based on a 
variation of MVC. (See Sun s web site for more on this, in an 
article entitled A Suing Architecture Overview .) In truth, MVC 
is probably best thought of as an application of several 
different design patterns, and although it seems 
straightforward on the surface it becomes more complex and 
subtle as you think about it more deeply and begin to apply 
it in different situations, and it can serve as a practical, if not 
simple, introduction to the patterns literature. Squeak in 
particular is moving toward a different model for its GUI, 


called Morphic, and Squeak users will want to learn about 
this as well, as an alternative to MVC. 

Programming Topics; Application Architecture 

<http://developerapple.com/techpubs/macosx/Cocoa/TasksAndConcepts/ 

Progra mm i ngTopt cs/App A rch itecture/i ndex htm l> 

A Swing Architecture Overview 

<h ttp://] a va, su n. com/pro ducts/jfc/tsc/a rt i cles/a re h itectu re/i n d e x, ht m I > 

Morphic - The Squeak User Interface 
<http://webs.sinectis.com.ar/jmvuletich/MorphicTutorial/Morphic.htmt> 

For a brief explanation of MVC and its terminology, 
as well as some of its shortcomings, check out Object 
Arts' page on the subject, and for alternative high-level 
descriptions see CERN's web site and Michael Callaghan's 
notes. If you want to delve deeper into MVC, the 
foundational paper How to use Model-View-ControHer 
provides a thorough treatment. Finally, IBM's web site has 
an extensive example of the pattern’s application in a Java 
program (which, to continue our theme, is informative 
even if you do not program in Java). 

Object Arts: Mode I - Vie w-Contro! le r framework 
<http://www.object-arts.com/EducationCentre/Overviews/MVC.htm> 

CERN: The Model-View-Controller Architecture 
<http://rd13doc.cemxh/Atlas/Notes/004/Note004-7.html> 

Michael Callaghan: Model-View-Controller Architecture 
<http://www.cms.dmu.ac.uk/-jmc/mvchtml> 

How to use Model-View-Controller (MVC) 
<http://st-www.cs.uiuc.edu/users/smarch/st-docs/mvchtml> 

Applying the Model-View-Controller Design Paradigm in VisualAge for Java 
<http://www7.software.ibm.com/vad.nsf/Data/Document2672> 

If you discover that Smalltalk’s development 
environment is fust what you have been looking for, you 
should take a look at ActiveDeveloper, which provides a 
similar environment for developing Cocoa applications, with 
a focus on rapid prototyping, debugging, and API 
exploration. Currently they do not have a version announced 
for the new r Mac OS X, but if we are lucky they have one 
under development. 

AdiveDeveloper 

<http://www.interactive-technology.com/Products/ActiveDeveloper.html> 

Enjoy your foray into Smalltalk development. It is a 
fascinating language, with recurring ties to Apple and the 
Macintosh — from the origins of the GUI at Xerox PARC, to 
Objective-C, to Squeak. There are many languages and 
development environments which are pleasant to work with, 
but the very culture of Smalltalk seems to be focused on fun 
and experimentation — it is unique and was designed from 
the start to genuinely be a joy to use, without compromising 
functionality or purity of design, I3D 
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